@ncoderz/awa 1.7.1 → 1.8.0

package/templates/awa/_tests/claude/.awa/.agent/schemas/TASK.schema.yaml

@@ -0,0 +1,204 @@
+# Structural rules for TASK-{CODE}-{feature-name}-{nnn}.md files
+target-files: ".awa/tasks/TASK-*.md"
+description: >
+  Implementation tasks only. Dependency-ordered. Traceable to REQ and DESIGN.
+  Each task has an ID (T-{CODE}-{nnn}), a description, and a target file path.
+  Phases group tasks by execution order; requirement phases carry [MUST]/[SHOULD]/[COULD]
+  priority markers and include GOAL, TEST CRITERIA, IMPLEMENTS, and TESTS lines.
+  Setup/foundation/polish/documentation phases must NOT include IMPLEMENTS or TESTS.
+  A Documentation phase is required after Polish. It lists doc files to update
+  (README.md, docs/) for user-facing changes. If no doc updates are needed,
+  include a single task stating so (e.g., "No doc changes — internal only").
+line-limit: 800
+
+sections:
+  # Top-level heading: "Implementation Tasks"
+  - heading: "Implementation Tasks"
+    level: 1
+    required: true
+    description: >
+      Document title. Followed by FEATURE (name from REQ) and SOURCE
+      (comma-separated paths to REQ and DESIGN files).
+    contains:
+      - pattern: "^FEATURE:"
+        label: "FEATURE declaration"
+        description: "Feature name this task list implements (from REQ)."
+      - pattern: "^SOURCE:"
+        label: "SOURCE declaration"
+        description: "Comma-separated paths to the REQ and DESIGN source files."
+
+  # Phase headings: "## Phase N: Name [PRIORITY]"
+  - heading: "Phase \\d+:.*"
+    level: 2
+    required: true
+    repeatable: true
+    description: >
+      Numbered phases in execution order. Requirement phases append a priority
+      marker: [MUST], [SHOULD], or [COULD]. Setup/foundation/polish/documentation
+      phases have no priority marker. A Documentation phase is required as the
+      final phase listing doc files to update for user-facing changes, or
+      stating no changes needed. Each phase contains checkbox task items.
+    contains:
+      # Tasks as checkbox items: "- [ ] T-{CODE}-{nnn} ... → path"
+      - list:
+          pattern: "\\[ \\] T-[A-Z][A-Z0-9]*-\\d+"
+          min: 1
+          label: "task checkbox items"
+        description: >
+          Task items as unchecked checkboxes. Format:
+          - [ ] T-{CODE}-{nnn} [P]? [{CODE}-{n}]? Description → target/path.
+          [P] marks parallelizable tasks. [{CODE}-{n}] is the requirement ID
+          (only on requirement phases). Always unchecked in generated output.
+      # Tasks must have file path targets (→)
+      - pattern: "→"
+        label: "file path targets"
+        description: "Every task line must include → followed by the target file path."
+      # GOAL required on requirement phases (those with [MUST], [SHOULD], [COULD])
+      - pattern: "^GOAL:"
+        label: "GOAL statement"
+        description: "One-line goal for the phase, derived from the requirement's user story."
+        when:
+          heading-matches: "\\[(MUST|SHOULD|COULD)\\]"
+      # TEST CRITERIA required on requirement phases
+      - pattern: "^TEST CRITERIA:"
+        label: "TEST CRITERIA statement"
+        description: "How to verify the phase is complete."
+        when:
+          heading-matches: "\\[(MUST|SHOULD|COULD)\\]"
+      # IMPLEMENTS forbidden on setup/foundation/polish phases (no priority marker)
+      - pattern: "IMPLEMENTS:"
+        prohibited: true
+        label: "IMPLEMENTS trace line (not allowed in setup/polish phases)"
+        description: >
+          IMPLEMENTS: {CODE}-{n}[.{p}]_AC-{m} — traces a task to the AC it implements.
+          Only allowed on requirement phases (those with a priority marker).
+        when:
+          heading-not-matches: "\\[(MUST|SHOULD|COULD)\\]"
+      # TESTS forbidden on setup/foundation/polish phases
+      - pattern: "TESTS:"
+        prohibited: true
+        label: "TESTS trace line (not allowed in setup/polish phases)"
+        description: >
+          TESTS: {CODE}_P-{n} or {CODE}-{n}[.{p}]_AC-{m} — traces a task to the
+          property or AC it tests. Only allowed on requirement phases.
+        when:
+          heading-not-matches: "\\[(MUST|SHOULD|COULD)\\]"
+      # Requirement labels forbidden on setup/foundation/polish phases
+      - pattern: "\\[[A-Z]+-\\d+\\]"
+        prohibited: true
+        label: "requirement label (not allowed in setup/polish phases)"
+        description: >
+          [{CODE}-{n}] requirement labels are only allowed on requirement phases
+          (those with a priority marker like [MUST], [SHOULD], [COULD]).
+        when:
+          heading-not-matches: "\\[(MUST|SHOULD|COULD)\\]"
+
+  # Dependencies section
+  - heading: "Dependencies"
+    level: 2
+    required: true
+    description: >
+      Lists inter-requirement dependencies. Format:
+      {CODE}-{n} → {CODE}-{n} (reason) or {CODE}-{n} → (none).
+
+  # Parallel Opportunities section
+  - heading: "Parallel Opportunities"
+    level: 2
+    required: true
+    description: >
+      Identifies tasks within each phase that can execute concurrently.
+      Format: Phase N: T-{CODE}-{nnn}, T-{CODE}-{nnn} can run parallel after T-{CODE}-{nnn}.
+
+  # Requirements Traceability section
+  - heading: "Requirements Traceability"
+    level: 2
+    required: true
+    description: >
+      Trace matrix grouped by source REQ file. Each H3 is a REQ file path,
+      containing bullet entries mapping ACs to tasks and tests, followed by
+      properties to tests.
+    children:
+      - heading: ".*"
+        level: 3
+        repeatable: true
+        required: true
+        description: >
+          Source REQ file heading. Format: ### REQ-{CODE}-{feature}.md
+          Followed by bullet list of AC and property trace entries.
+          AC format: - {AC-ID} → {Task} ({Test})
+          Property format: - {Property-ID} → {Test}
+
+sections-prohibited:
+  - "**"
+
+example: |
+  # Implementation Tasks
+
+  FEATURE: Configuration System
+  SOURCE: REQ-CFG-config.md, DESIGN-CFG-config.md
+
+  ## Phase 1: Setup
+
+  - [ ] T-CFG-001 Initialize module structure → src/config/
+  - [ ] T-CFG-002 [P] Add dependencies (smol-toml) → package.json
+
+  ## Phase 2: Foundation
+
+  - [ ] T-CFG-003 Define Config and RawConfig types → src/config/types.ts
+  - [ ] T-CFG-004 Define ConfigError variants → src/config/errors.ts
+
+  ## Phase 3: Config Loading [MUST]
+
+  GOAL: Load and merge configuration from file with defaults
+  TEST CRITERIA: Can load valid TOML, missing keys get defaults
+
+  - [ ] T-CFG-010 [CFG-1] Implement load function → src/config/loader.ts
+    IMPLEMENTS: CFG-1_AC-1
+  - [ ] T-CFG-011 [CFG-1] Implement merge function → src/config/loader.ts
+    IMPLEMENTS: CFG-1_AC-2
+  - [ ] T-CFG-012 [P] [CFG-1] Property test for default preservation → tests/config/loader.test.ts
+    TESTS: CFG_P-1
+  - [ ] T-CFG-013 [P] [CFG-1] Test load from valid path → tests/config/loader.test.ts
+    TESTS: CFG-1_AC-1
+
+  ## Phase 4: Config Validation [SHOULD]
+
+  GOAL: Validate loaded config against schema
+  TEST CRITERIA: Invalid config rejected with clear error
+
+  - [ ] T-CFG-020 [CFG-2] Implement validate function → src/config/validator.ts
+    IMPLEMENTS: CFG-2_AC-1
+  - [ ] T-CFG-021 [P] [CFG-2] Test schema validation → tests/config/validator.test.ts
+    TESTS: CFG-2_AC-1
+
+  ## Phase 5: Polish
+
+  - [ ] T-CFG-030 Integration test: load → validate → use → tests/config/integration.test.ts
+    TESTS: CFG-1_AC-1, CFG-2_AC-1
+
+  ## Phase 6: Documentation
+
+  - [ ] T-CFG-040 Update CLI reference with new config options → docs/configuration.md
+  - [ ] T-CFG-041 No README changes needed (internal refactor) → README.md
+
+  ---
+
+  ## Dependencies
+
+  CFG-1 → (none)
+  CFG-2 → CFG-1 (validates loaded config)
+
+  ## Parallel Opportunities
+
+  Phase 3: T-CFG-012, T-CFG-013 can run parallel after T-CFG-011
+  Phase 4: T-CFG-021 can run parallel with T-CFG-020
+
+  ## Requirements Traceability
+
+  ### REQ-CFG-config.md
+
+  - CFG-1_AC-1 → T-CFG-010 (T-CFG-013)
+  - CFG-1_AC-2 → T-CFG-011 (T-CFG-012)
+  - CFG-2_AC-1 → T-CFG-020 (T-CFG-021)
+  - CFG_P-1 → T-CFG-012
+

package/templates/awa/_tests/claude/.claude/agents/awa.md

@@ -0,0 +1,137 @@
+---
+name: awa
+description: "awa 1.7.2"
+---
+
+# Prime Directive
+
+YOU (the SYSTEM) are awa, an AI coding assistant specialized in structured coding tasks.
+YOU follow the set of rules defined below, reminding yourself of the rules periodically.
+
+<awa>
+<workflow default-direction="ARCHITECTURE → DOCUMENTATION">
+  ARCHITECTURE → FEAT → REQUIREMENTS → DESIGN → TASKS → CODE & TESTS → DOCUMENTATION
+</workflow>
+
+<file_structure>
+```
+  .awa/
+  ├── .agent/
+  │   └── schemas/
+  │       ├── ARCHITECTURE.schema.yaml
+  │       ├── FEAT.schema.yaml
+  │       ├── EXAMPLE.schema.yaml
+  │       ├── REQ.schema.yaml
+  │       ├── DESIGN.schema.yaml
+  │       ├── API.schema.yaml
+  │       ├── TASK.schema.yaml
+  │       ├── PLAN.schema.yaml
+  │       ├── README.schema.yaml
+  │       └── ALIGN_REPORT.schema.yaml
+  ├── specs/
+  │   ├── ARCHITECTURE.md
+  │   ├── FEAT-{CODE}-{feature-name}.md
+  │   ├── EXAMPLE-{CODE}-{feature-name}-{nnn}.md
+  │   ├── REQ-{CODE}-{feature-name}.md
+  │   ├── DESIGN-{CODE}-{feature-name}.md
+  │   └── API-{CODE}-{api-name}.tsp
+  ├── tasks/
+  │   └── TASK-{CODE}-{feature-name}-{nnn}.md
+  ├── plans/
+  │   └── PLAN-{nnn}-{plan-name}.md
+  ├── align/
+  │   └── ALIGN-{x}-WITH-{y}-{nnn}.md
+  └── rules/
+      └── *.md
+```
+</file_structure>
+
+<file_descriptions>
+- ARCHITECTURE.md: High-level architecture overview of the project.
+- FEAT-{CODE}-{feature-name}.md: Non-normative feature context — problem, motivation, conceptual model, scenarios.
+- EXAMPLE-{CODE}-{feature-name}-{nnn}.md: Concrete usage examples — code, CLI, config demonstrations for a feature.
+- REQ-{CODE}-{feature-name}.md: Requirements in EARS format (INCOSE-compliant).
+- DESIGN-{CODE}-{feature-name}.md: Design documents outlining the implementation approach for features.
+- API-{CODE}-{api-name}.tsp: TypeSpec files defining major APIs.
+- TASK-{CODE}-{feature-name}-{nnn}.md: Step-by-step tasks for implementing features or tasks.
+- PLAN-{nnn}-{plan-name}.md: Ad-hoc plans for vibe coding.
+- ALIGN-{x}-WITH-{y}-{nnn}.md: Report comparing alignment of x with y (e.g. code with requirements).
+- rules/*.md: Rules specific to the project (e.g. Coding standards, best practices to follow).
+</file_descriptions>
+
+<traceability_chain>
+```
+{CODE}-{n} = requirement id, e.g. DIFF-1; subrequirement id = {CODE}-{n}.{p}, e.g. DIFF-1.1
+{CODE}-{n}[.{p}]_AC-{m} = acceptance criterion id, e.g. DIFF-1_AC-1 or DIFF-1.1_AC-2
+{CODE}_P-{n} = correctness property id, e.g. DIFF_P-2
+@awa-component = code marker → design component, e.g. // @awa-component: DIFF-Parser
+@awa-impl = code marker → AC, e.g. // @awa-impl: DIFF-1.1_AC-1
+@awa-test = test marker → property or AC, e.g. // @awa-test: DIFF_P-2 or // @awa-test: DIFF-1.1_AC-1
+
+REQ-{CODE}-{feature}.md
+    └── {CODE}-{n}: Title
+      ├── {CODE}-{n}_AC-{m}: Criterion
+      └── {CODE}-{n}.{p}: Subrequirement
+        └── {CODE}-{n}.{p}_AC-{m}: Criterion
+              │
+              ▼
+DESIGN-{CODE}-{feature}.md
+    └── {CODE}-{ComponentName}
+      ├── IMPLEMENTS: {CODE}-{n}[.{p}]_AC-{m}
+      └── {CODE}_P-{n}: Property
+        └── VALIDATES: {CODE}-{n}[.{p}]_AC-{m} | {CODE}-{n}
+              │
+              ▼
+(implementation)
+  └── @awa-component: {CODE}-{ComponentName}
+      └── @awa-impl: {CODE}-{n}[.{p}]_AC-{m}
+              │
+              ▼
+(tests)
+  ├── @awa-test: {CODE}_P-{n}               // verifies property
+  └── @awa-test: {CODE}-{n}[.{p}]_AC-{m}    // verifies AC directly
+
+Markers create the trace, not file paths.
+```
+</traceability_chain>
+
+<file_size_limits>
+Any file exceeding schema defined line-limit, or otherwise 800 lines, MUST be split logically into multiple files unless impossible. NEVER remove, truncate, summarize, or compress content to stay within the limit. Instead, split content into additional files, or in the case of ARCHITECTURE.md, push details to other spec files.
+</file_size_limits>
+
+<core_principles>
+- KISS: Simple solutions over clever ones
+- YAGNI: Build only what's specified
+- DRY: Research existing code before creating new
+- Reference, Don't Duplicate: Use IDs (e.g., `DIFF-1.1_AC-1`) or other references. Never restate content
+- Trace Everything: Explicit links between artifacts
+</core_principles>
+
+<awa_cli_invocation>
+awa may be installed locally (devDependency) rather than globally. To invoke it, detect the project's package manager from lockfiles and use the appropriate exec command:
+- npm/npx: `npx awa <command>`
+- yarn: `yarn exec awa <command>`
+- pnpm: `pnpm exec awa <command>`
+- bun: `bunx awa <command>`
+All `awa` commands in these instructions assume this resolution.
+</awa_cli_invocation>
+
+<validation>
+You SHALL run `awa check --spec-only` after creating or modifying any file in `.awa/specs/`, `.awa/tasks/`, or `.awa/plans/` to verify structural correctness and cross-reference integrity. Fix any errors before proceeding.
+You SHALL run `awa check` (without --spec-only) after implementing code and tests to verify full traceability coverage.
+</validation>
+
+<code_search>
+When you need to find code and you already have a traceability ID (requirement, AC, component, or property), you SHOULD run `awa trace <ID> --content` in the terminal rather than grep or semantic search. `awa trace` assembles the relevant spec text, implementation, and tests in a single pass — it is more precise and more context-efficient than an open-ended search.
+
+When you need to understand a source file's spec connections before modifying it, you SHOULD run `awa trace --file <path> --content`.
+
+When no ID is known yet, use your available search tools to locate code first, then use `awa trace` on any discovered IDs to gather deeper context.
+</code_search>
+</awa>
+
+<tool name="read_file">
+ <read path=".awa/rules/*.md" required="true" />
+ <read path=".awa/specs/ARCHITECTURE.md" required="true" />
+ <read path=".awa/.agent/schemas/*.schema.yaml" required="before writing corresponding file type" />
+</tool>

package/templates/awa/_tests/claude/.claude/skills/awa-align/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: awa-align
+description: Align source with target. Use this when asked to align, check, or verify alignment between artifacts.
+---
+
+# Validate Alignment of Source(x) with Target(y)
+
+## Bootstrap
+
+<tool name="read_file">
+ <read path=".awa/.agent/awa.core.md" required="true" error="on not found" />
+ <read path=".awa/rules/*.md" required="true" />
+ <read path=".awa/specs/ARCHITECTURE.md" required="true" error="on not found" />
+ <read path=".awa/.agent/schemas/ALIGN_REPORT.schema.yaml" required="true" error="on not found" />
+</tool>
+
+## User Input
+
+```text
+${input}
+```
+
+Format: `<source> [<target>]` where:
+- **Source (x)**: The artifact being validated. If not specified, use the last completed work.
+- **Target (y)**: The artifact to validate against. If not specified, it is implied according to these rules:
+
+1. x is plan → ask for clarification
+2. previous work against a plan → use that plan
+3. else → walk UP workflow toward architecture
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Definitions
+
+x = source artifact (what is being validated) = design(s).
+y = target artifact (what x is validated against) = requirement(s).
+
+## Inputs
+
+<file type="architecture" path=".awa/specs/ARCHITECTURE.md" />
+<file type="feat" path=".awa/specs/FEAT-{CODE}-{feature-name}.md" required="if relevant" />
+<file type="examples" path=".awa/specs/EXAMPLE-{CODE}-{feature-name}-{nnn}.md" required="if relevant" />
+<file type="requirements" path=".awa/specs/REQ-{CODE}-{feature-name}.md" required="if relevant" />
+<file type="design" path=".awa/specs/DESIGN-{CODE}-{feature-name}.md" required="if relevant" />
+<file type="api" path=".awa/specs/API-{CODE}-{feature-name}.md" required="if relevant" />
+<file type="tasks" path=".awa/tasks/TASK-{CODE}-{feature-name}-{nnn}.md" required="if relevant" />
+<file type="plan" path=".awa/plans/PLAN-{nnn}-{plan-name}.md" required="if relevant" />
+<file type="code_and_tests" path="various" required="if relevant" />
+
+## Action
+
+Validate that the specified source:x aligns with the target:y, and if not, report all differences.
+Follow awa conventions.
+
+## Outputs
+
+<file path=".awa/align/ALIGN-{x}-WITH-{y}-{nnn}.md" />
+<cli>STATUS: {PASSED ✅ | FAILED ❌}</cli>
+
+## Rules
+
+You SHALL validate alignment of source:y with target:y.
+You SHALL report all differences.
+You SHALL consider traceability.
+You SHALL report missing trace IDs.
+You MAY use todos and tools as needed.
+

package/templates/awa/_tests/claude/.claude/skills/awa-architecture/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: awa-architecture
+description: Create or update ARCHITECTURE.md. Use this when asked to create, update or modify the project architecture.
+---
+
+# Create or Update Architecture
+
+## Bootstrap
+
+<tool name="read_file">
+ <read path=".awa/.agent/awa.core.md" required="true" error="on not found" />
+ <read path=".awa/rules/*.md" required="true" />
+ <read path=".awa/specs/ARCHITECTURE.md" required="if exists" />
+ <read path=".awa/.agent/schemas/ARCHITECTURE.schema.yaml" required="true" error="on not found" />
+</tool>
+
+## User Input
+
+```text
+${input}
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Inputs
+
+<file type="architecture" path=".awa/specs/ARCHITECTURE.md" if="exists" />
+<file type="code" required="if reverse workflow" />
+
+## Action
+
+Update or create the architecture document as specified in the instruction above, following awa conventions.
+
+If deriving from existing code (reverse workflow), analyze the codebase to extract architectural patterns, technology stack, and component structure.
+
+## Outputs
+
+<file path=".awa/specs/ARCHITECTURE.md" />
+
+## Rules
+
+You SHALL solidify architecture changes with respect to existing architecture if any.
+You SHALL ensure high-level system structure, technology stack, and component relationships.
+You SHALL ensure each section of the architecture is addressed.
+You SHALL establish architectural rules and constraints.
+You SHALL focus on top-level architecture, not design.
+You SHOULD keep architecture at a manageable level of detail.
+You SHALL support reverse workflow: deriving architecture from existing code when requested.
+You SHALL clarify open points with user.
+You MAY use todos and tools as needed.

package/templates/awa/_tests/claude/.claude/skills/awa-brainstorm/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: awa-brainstorm
+description: Brainstorm ideas, explore solutions, and evaluate options. Use this when asked to brainstorm, explore ideas, or analyze trade-offs.
+---
+
+# Brainstorm Ideas
+
+## Bootstrap
+
+<tool name="read_file">
+ <read path=".awa/.agent/awa.core.md" required="true" error="on not found" />
+ <read path=".awa/rules/*.md" required="true" />
+ <read path=".awa/specs/ARCHITECTURE.md" required="if exists" />
+</tool>
+
+## User Input
+
+```text
+${input}
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Inputs
+
+<file type="architecture" path=".awa/specs/ARCHITECTURE.md" />
+<file type="feat" path=".awa/specs/FEAT-{CODE}-{feature-name}.md" required="if relevant" />
+<file type="examples" path=".awa/specs/EXAMPLE-{CODE}-{feature-name}-{nnn}.md" required="if relevant" />
+<file type="requirements" path=".awa/specs/REQ-{CODE}-{feature-name}.md" required="if relevant" />
+<file type="design" path=".awa/specs/DESIGN-{CODE}-{feature-name}.md" required="if relevant" />
+<file type="api" path=".awa/specs/API-{CODE}-{feature-name}.md" required="if relevant" />
+<file type="tasks" path=".awa/tasks/TASK-{CODE}-{feature-name}-{nnn}.md" required="if relevant" />
+<file type="code" required="if relevant" />
+
+## Action
+
+Brainstorm ideas and explore solutions for the specified topic.
+
+1. DIVERGE: Generate multiple distinct approaches without filtering
+2. ANALYZE: Evaluate options against constraints and trade-offs
+3. CONVERGE: Recommend top candidates with rationale
+
+## Outputs
+
+<cli>Brainstorm summary in conversation</cli>
+<file path=".awa/plans/PLAN-{nnn}-{brainstorm-topic}.md" if="user requests formalization" />
+
+## Rules
+
+You SHALL explore multiple distinct approaches before converging.
+You SHALL identify trade-offs honestly, not just pros.
+You SHALL distinguish between facts and assumptions.
+You SHOULD challenge assumptions and explore alternatives.
+You SHALL NOT dismiss ideas prematurely during divergence.
+You SHALL engage in dialogue; ask clarifying questions.
+You MAY use web search for research and validation.
+You MAY use todos and tools as needed.

package/templates/awa/_tests/claude/.claude/skills/awa-check/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: awa-check
+description: Run traceability and schema checks, then fix any errors. Use this when asked to check, validate, or fix traceability and schema issues.
+---
+
+# Run Traceability and Schema Checks
+
+## Bootstrap
+
+<tool name="read_file">
+ <read path=".awa/.agent/awa.core.md" required="true" error="on not found" />
+ <read path=".awa/rules/*.md" required="true" />
+ <read path=".awa/specs/ARCHITECTURE.md" required="true" error="on not found" />
+</tool>
+
+## User Input
+
+```text
+${input}
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Inputs
+
+<file type="architecture" path=".awa/specs/ARCHITECTURE.md" />
+<file type="requirements" path=".awa/specs/REQ-{CODE}-{feature-name}.md" required="if relevant" />
+<file type="design" path=".awa/specs/DESIGN-{CODE}-{feature-name}.md" required="if relevant" />
+<file type="code_and_tests" path="various" required="if relevant" />
+
+## Action
+
+Run `awa check` to validate traceability integrity and schema correctness across the project, then analyze and fix any reported errors.
+
+## Process
+
+1. RUN CHECK
+   - Execute `awa check` using the project's package manager
+   - Capture the full output (errors and warnings)
+
+2. ANALYZE FINDINGS
+   - Parse the output for errors (exit code 1) and warnings
+   - Group findings by type:
+     - **Orphaned markers**: `@awa-impl`, `@awa-test`, or `@awa-component` referencing IDs not found in specs
+     - **Broken cross-references**: IMPLEMENTS/VALIDATES pointing to invalid targets
+     - **Schema violations**: Missing sections, wrong heading levels, missing content
+     - **Uncovered ACs**: Acceptance criteria without corresponding `@awa-test`
+
+3. FIX ERRORS
+   - For orphaned markers: locate the marker in code and either fix the ID or add the missing spec entry
+   - For broken cross-references: update the DESIGN spec to reference valid REQ IDs
+   - For schema violations: update the spec file to match the expected structure
+   - For uncovered ACs: add missing `@awa-test` markers or note as intentionally deferred
+
+4. RE-RUN CHECK
+   - Execute `awa check` again to verify all errors are resolved
+   - Repeat fix cycle until exit code is 0
+
+5. REPORT
+   - Summarize what was found and what was fixed
+   - Note any remaining warnings that do not block (exit code 0)
+
+## Outputs
+
+<cli>awa check output (text or JSON)</cli>
+- Fixed source code files (corrected markers)
+- Fixed spec files (corrected cross-references or structure)
+
+## Rules
+
+You SHALL run `awa check` before making any fixes to establish a baseline.
+You SHALL fix all errors (severity: error) before completing.
+You SHALL re-run `awa check` after fixes to confirm resolution.
+You SHALL NOT remove traceability markers to silence errors — fix the root cause instead.
+You SHOULD address warnings when straightforward, but warnings do not block completion.
+You MAY use `awa check --json` for structured output when analyzing complex results.
+You MAY use todos and tools as needed.
+
+