feat: enhance validation and documentation across multiple modules

Author: Akagi201

README.md

@@ -91,13 +91,17 @@ pb-spec init --ai all -g       # install globally to each agent's home/config di
 
 ## Supported AI Tools
 
-| AI Tool | Target Directory | File Format |
-|---|---|---|
-| Claude Code | `.claude/skills/pb-<name>/SKILL.md` | YAML frontmatter + Markdown |
-| VS Code Copilot | `.github/prompts/pb-<name>.prompt.md` | Markdown (no frontmatter) |
-| OpenCode | `.opencode/skills/pb-<name>/SKILL.md` | YAML frontmatter + Markdown |
-| Gemini CLI | `.gemini/commands/pb-<name>.toml` | TOML (`description` + `prompt`) |
-| Codex | `.codex/prompts/pb-<name>.md` | YAML frontmatter + Markdown |
+All platform adapters are **fully implemented** and production-ready. Each platform has been tested for path generation, content rendering, and file installation.
+
+| AI Tool | Status | Target Directory | File Format | Global Install |
+|---|---|---|---|---|
+| Claude Code | ✅ Complete | `.claude/skills/pb-<name>/SKILL.md` | YAML frontmatter + Markdown | ✅ `~/.claude/skills/` |
+| VS Code Copilot | ✅ Complete | `.github/prompts/pb-<name>.prompt.md` | Markdown (no frontmatter) | ✅ `~/.copilot/prompts/` |
+| OpenCode | ✅ Complete | `.opencode/skills/pb-<name>/SKILL.md` | YAML frontmatter + Markdown | ✅ `~/.config/opencode/skills/` |
+| Gemini CLI | ✅ Complete | `.gemini/commands/pb-<name>.toml` | TOML (`description` + `prompt`) | ✅ `~/.gemini/commands/` |
+| Codex | ✅ Complete | `.codex/prompts/pb-<name>.md` | YAML frontmatter + Markdown | ✅ `~/.codex/prompts/` |
+
+For detailed implementation information, see [docs/platform-implementation-status.md](docs/platform-implementation-status.md).
 
 ## CLI Reference
 
@@ -158,7 +162,7 @@ This stronger contract does not add a new command or side-channel validator. The
 
 ### 2. `/pb-plan <requirement>` — Design & Task Planning
 
-Takes a natural-language requirement and produces a complete feature spec:
+Takes source material in arbitrary format and produces a complete feature spec. You can hand it raw design docs, rough notes, copied requirements, partial design drafts, or mixed-format planning input without wrapping that material in a special pb-plan prompt recipe:
 
 ```text
 specs/<YYYY-MM-DD-NO-feature-name>/
@@ -178,6 +182,8 @@ It also performs two additional planning audits before implementation starts:
 - Template identity alignment: if the repo still contains generic crate/package/module names from a scaffold, `pb-plan` must front-load renaming those identifiers to project-matching names.
 - Risk-based advanced testing: property testing is planned by default for broad input-domain logic, while fuzzing and benchmarks are added only when the feature profile justifies them. Tool selection follows repo language conventions: `Hypothesis` / `fast-check` / `proptest`, `Atheris` / `jazzer.js` / `cargo-fuzz`, and `pytest-benchmark` / `Vitest Bench` / `criterion`.
 
+It should also normalize the incoming source material into a source requirement ledger and use multiple fresh subagents when that improves quality, typically separating source requirement extraction, live codebase analysis, and spec reconciliation. Before finalizing the spec, `pb-plan` should reconcile the extracted source requirements against the generated `design.md`, `tasks.md`, and `features/*.feature` so missing requirements are closed in the planning phase instead of being discovered later during `pb-build`.
+
 It also adds an explicit **Architecture Decisions** section to `design.md`. For work that introduces a new boundary or is likely to exceed 200 lines, planning must evaluate **SRP**, **DIP**, and the classic patterns **Factory**, **Strategy**, **Observer**, **Adapter**, and **Decorator**. The chosen pattern must be justified against alternatives and checked against the code-simplification lens so the design stays simpler, not just more abstract.
 
 The resulting `design.md`, `tasks.md`, and `features/*.feature` files are also the workflow's type carrier in plain markdown. `pb-plan` keeps the current artifact family and command surface, but those artifacts now need explicit contract fields so downstream stages can validate readiness without inventing a separate YAML or JSON schema.

docs/contract.md

@@ -407,7 +407,42 @@ A spec is build-eligible when all of the following are true:
 
 Future validator versions may extend build eligibility checks to include stronger cross-link validation.
 
-## 12. Validator-Ready Priorities
+## 12. Validation Type System
+
+### 12.1 Structured Validation Results
+
+The validation system uses structured types for better error handling and reporting:
+
+| Type | Purpose |
+| :--- | :--- |
+| `ValidationResult` | Collection of errors and warnings with severity levels |
+| `ValidationError` | Single validation issue with file, line, column context |
+| `ErrorLevel` | Severity enum: `ERROR`, `WARNING`, `INFO` |
+
+### 12.2 Backward Compatibility
+
+For backward compatibility, the validation functions maintain two interfaces:
+
+| Function | Return Type | Purpose |
+| :--- | :--- | :--- |
+| `validate_design_file()` | `list[str]` | Legacy interface returning error strings |
+| `validate_design_file_structured()` | `ValidationResult` | New interface with structured errors |
+| `validate_task_file()` | `list[str]` | Legacy interface returning error strings |
+| `validate_task_file_structured()` | `ValidationResult` | New interface with structured errors |
+
+The legacy functions return `[error.message for error in result.errors]` to maintain backward compatibility with existing code and tests.
+
+### 12.3 Feature Parsing Types
+
+The feature parsing system uses structured types:
+
+| Type | Purpose |
+| :--- | :--- |
+| `FeatureScenario` | Parsed Gherkin scenario with file, line number, and outline flag |
+| `parse_feature_file()` | Returns `list[FeatureScenario]` for structured access |
+| `get_scenario_by_name()` | Finds a specific scenario by name |
+
+## 13. Validator-Ready Priorities
 
 The first validator tranche should prioritize the narrowest high-value checks:
 

docs/platform-implementation-status.md

@@ -0,0 +1,97 @@
+# Platform Implementation Status
+
+All platform adapters in pb-spec are **fully implemented** and production-ready.
+
+## Supported Platforms
+
+| Platform | Status | Directory Structure | File Format | Global Install Support |
+| :--- | :--- | :--- | :--- | :--- |
+| **Claude Code** | ✅ Complete | `.claude/skills/<name>/SKILL.md` | YAML frontmatter + Markdown | ✅ Yes (`~/.claude/skills/`) |
+| **VS Code Copilot** | ✅ Complete | `.github/prompts/<name>.prompt.md` | Plain Markdown | ✅ Yes (`~/.copilot/prompts/`) |
+| **OpenCode** | ✅ Complete | `.opencode/skills/<name>/SKILL.md` | YAML frontmatter + Markdown | ✅ Yes (`~/.config/opencode/skills/`) |
+| **Gemini CLI** | ✅ Complete | `.gemini/commands/<name>.toml` | TOML (description + prompt) | ✅ Yes (`~/.gemini/commands/`) |
+| **OpenAI Codex** | ✅ Complete | `.codex/prompts/<name>.md` | YAML frontmatter + Markdown | ✅ Yes (`~/.codex/prompts/`) |
+
+## Implementation Details
+
+### Claude Code (`claude.py`)
+
+- Uses SKILL.md files with YAML frontmatter
+- Supports `CLAUDE_CONFIG_DIR` environment variable for custom config location
+- Installs reference files alongside skill files
+
+### VS Code Copilot (`copilot.py`)
+
+- Uses `.prompt.md` files without frontmatter
+- Simplest format - just raw prompt content
+- Self-contained prompts (no reference files)
+
+### OpenCode (`opencode.py`)
+
+- Uses SKILL.md files with YAML frontmatter
+- Supports XDG Base Directory specification (`XDG_CONFIG_HOME`)
+- Installs reference files alongside skill files
+
+### Gemini CLI (`gemini.py`)
+
+- Uses TOML format with `description` and `prompt` fields
+- Self-contained prompts (no reference files)
+- Handles quote escaping in TOML values
+
+### OpenAI Codex (`codex.py`)
+
+- Uses `.md` files with YAML frontmatter
+- Supports `CODEX_HOME` environment variable for custom config location
+- Self-contained prompts (no reference files)
+
+## Platform-Specific Features
+
+### Skill Loading Strategy
+
+- **Claude, OpenCode**: Use `load_skill_content()` (SKILL.md with frontmatter)
+- **Copilot, Gemini, Codex**: Use `load_prompt()` (simple prompt files)
+
+### Reference File Installation
+
+- **Claude, OpenCode**: Install reference files in `references/` subdirectory
+- **Copilot, Gemini, Codex**: Self-contained, no reference files needed
+
+## Usage Examples
+
+```bash
+# Install for all platforms
+pb-spec init --ai all
+
+# Install for specific platform
+pb-spec init --ai claude
+pb-spec init --ai copilot
+pb-spec init --ai opencode
+pb-spec init --ai gemini
+pb-spec init --ai codex
+
+# Global installation
+pb-spec init --ai claude -g
+```
+
+## Testing
+
+All platform adapters are tested in `tests/test_platforms.py`:
+
+- Path generation (local and global)
+- Content rendering
+- File installation
+- Idempotency (skip existing files without `--force`)
+
+## Contributing
+
+When adding new platform support:
+
+1. Create a new file in `src/pb_spec/platforms/`
+2. Inherit from `Platform` base class
+3. Implement required abstract methods:
+   - `name` property
+   - `get_skill_path()` method
+   - `render_skill()` method
+4. Add platform to `PLATFORMS` dict in `src/pb_spec/platforms/__init__.py`
+5. Add tests in `tests/test_platforms.py`
+6. Update this documentation