Feature idea: /analyze-spec command for pre-implementation spec validation

[phil-cc]

Problem & Motivation

Agent OS has a well-defined shaping workflow: /plan-product establishes product context, /discover-standards codifies tribal knowledge, and /shape-spec produces a structured spec folder. What is missing is any validation step between shaping and implementation.

The artifacts produced by /shape-spec are written collaboratively in conversation - they are not machine-generated from a single source of truth. As a result, inconsistencies can silently appear:

• shape.md describes scope that never makes it into a task in plan.md
• plan.md tasks reference components or behaviors never discussed in shape.md
• standards.md contains rules that conflict with architectural choices in plan.md
• Decisions in shape.md quietly contradict each other
• Tasks duplicate effort or are ordered in ways that do not make logical sense

These issues are invisible until implementation begins - at which point they surface as confusion, blocked tasks, or bugs. The earlier they are caught, the cheaper they are to fix.

Proposed Change

A new command: /analyze-spec

It sits between /shape-spec and implementation in the workflow:

/plan-product        - establish product context
/discover-standards  - codify standards
/shape-spec          - shape and document the feature spec
/analyze-spec        - validate consistency before implementing  <-- new
[implementation]     - write the code

The command is strictly read-only - it never modifies any file. It:

1. Locates the target spec folder in agent-os/specs/ (defaults to most recent, accepts a partial name argument)
2. Verifies plan.md and shape.md exist
3. Builds a Scope Inventory from shape.md and a Task Inventory from plan.md
4. Runs five detection passes:
   • Coverage - scope items with no tasks, tasks with no scope backing
   • Ambiguity - vague adjectives (fast, secure, robust) without measurable criteria, placeholder language
   • Standards alignment - plan tasks that conflict with MUST/MUST NOT rules in standards.md
   • Internal consistency - technology conflicts, naming drift, task ordering violations across artifacts
   • Reference validation - file paths in references.md that no longer exist
5. Assigns CRITICAL / HIGH / MEDIUM / LOW severity to each finding
6. Outputs a structured Markdown report with a coverage summary table and metrics
7. Offers to suggest remediation edits - but does not apply any automatically

Alternatives considered:

• Folding this into /shape-spec as a final step - rejected because it conflates shaping with validation; they serve different moments and users
• Requiring a tasks.md separate from plan.md (as other tools do) - rejected to stay consistent with the existing Agent OS artifact structure

User Experience Impact

The command adds one optional but recommended step to the existing workflow. Users who skip it are unaffected - no existing commands change.

For users who run it, the output is a single Markdown report in the conversation. No files are written. The report gives a clear go / no-go signal before implementation starts, with specific, actionable findings rather than generic warnings.

Example output structure:

| ID   | Category    | Severity | Location         | Summary                                      |
|------|-------------|----------|------------------|----------------------------------------------|
| C-01 | Coverage    | CRITICAL | shape.md: Scope  | Token refresh flow has no task in plan.md    |
| S-01 | Standards   | HIGH     | plan.md: Task 7  | Task 7 conflicts with api/response-format    |
| A-01 | Ambiguity   | MEDIUM   | shape.md         | "fast" has no measurable latency target      |

With a coverage summary:

| Scope Item      | Tasks       | Status    |
|-----------------|-------------|-----------|
| OAuth login     | T-01, T-02  | Covered   |
| Token refresh   | -           | UNCOVERED |

Updating & Compatibility Considerations

• Purely additive - no existing commands are modified
• No new file formats introduced; the command reads the artifacts /shape-spec already produces
• Works with or without standards.md and references.md present (skips those passes gracefully)
• The README and /shape-spec output could reference /analyze-spec as a recommended next step, but that is optional
• No changes to config.yml or any profile required

Prior Art

This is inspired by similar validation steps in spec-management tools (e.g. Spec Kit's analyze command), adapted to match Agent OS's artifact structure and Markdown-driven command model rather than shell scripts or YAML hook systems.

Happy to submit a PR with the command file if this direction gets traction.