Aget Enhance Spec

/aget-enhance-spec

Guide agents through the core specification enhancement lifecycle. Provides governed workflow for spec creation, updates, cross-reference wiring, and validation.

Purpose

Replace ad-hoc specification enhancement with a repeatable, governed 7-phase process derived from 5 independent plans across 3 agents (L622). This is the Generator layer (ADR-008 step 3), built on SOP_specification_enhancement.md (Advisory) and SKILL-041 spec (Strict).

Input

$ARGUMENTS - Enhancement category and optional spec path.

Format: <CATEGORY> [spec-path] [--version <target-version>]

Categories: NEW, UPDATE, ADD-REQ, WIRE, CONSOLIDATE, DEPRECATE

Examples:

• /aget-enhance-spec NEW specs/AGET_FOO_SPEC.md
• /aget-enhance-spec UPDATE aget/specs/AGET_SOP_SPEC.md --version 1.2.0
• /aget-enhance-spec WIRE aget/specs/SKILL_NAMING_CONVENTION_SPEC.md
• /aget-enhance-spec ADD-REQ aget/specs/AGET_SOP_SPEC.md

Phase Selection

Not all categories require all phases. Use this table to determine which phases to execute:

Execution

Step 1: Parse Input

IF no arguments provided:
  Prompt: "What type of enhancement? (NEW, UPDATE, ADD-REQ, WIRE, CONSOLIDATE, DEPRECATE)"
  Prompt: "Path to spec? (leave blank for NEW)"

IF category not in valid list:
  Error: "Invalid category. Valid: NEW, UPDATE, ADD-REQ, WIRE, CONSOLIDATE, DEPRECATE"

IF category in (UPDATE, ADD-REQ, WIRE) AND no spec path:
  Error: "Spec path required for {category} enhancements"

Determine phase list from Phase Selection table above.

Step 2: Phase 0 — Trigger & Diagnosis

Objective: Identify the specification gap and gather evidence.

Execute:

1. If spec path provided, read the spec file and extract current version, status, requirement count

2. Search for related L-docs:

   grep -l "<topic_keywords>" .aget/evolution/L*.md
   

3. Search for related specs:

   ls specs/ aget/specs/ 2>/dev/null | grep -i "<topic>"
   

4. Document findings as evidence table:

   | Evidence | Source | Impact |
   |----------|--------|--------|
   | <finding> | <L-doc or spec> | <why this matters> |
   

5. Governance classification (L624, R-ENHANCE-SPEC-031/032):

   Determine governance level:
   IF spec path is under aget/ or aget-framework/ (public):
     IF category is UPDATE or NEW:
       REQUIRE: PROJECT_PLAN before proceeding past Phase 0
       Check: does PROJECT_PLAN exist for this enhancement?
       IF not: "PROJECT_PLAN required for public framework UPDATE/NEW. Create one first."
     ELSE (ADD-REQ, WIRE):
       Enhancement_Decision_Log (produced at Step 9) is sufficient
   ELSE (private agent spec):
     Enhancement_Decision_Log is sufficient
   

USER CHECKPOINT: Present evidence table and governance level, then ask:

Enhancement Category: <CATEGORY>
Target: <spec path or "new spec">
Evidence: <count> sources found
Governance: <PROJECT_PLAN required | Enhancement_Decision_Log sufficient>

Confirm category and proceed? (yes/adjust category/abort)

Exit Criteria: Category confirmed. Evidence documented. Gap clearly stated. Governance level determined.

Step 2.5: Phase 0.5 — Maturity Assessment (L682)

Objective: Score the target spec's current maturity level to inform enhancement scope.

Execute:

1. If spec exists (UPDATE, ADD-REQ, WIRE), assess against RUBRIC_specification_maturity_v1.0:

   Content:     C_ (0=Implicit, 1=Intent, 2=Structured, 3=Grounded, 4=Verified, 5=Wired)
   Enforcement: E_ (0=Unenforceable, 1=Advisory, 2=Detectable, 3=Preventable, 4=Structural)
   Adoption:    A_ (0=Unaware, 1=Aware, 2=Compliant, 3=Internalized, 4=Forward)
   Process:     P_ (0=Ad-hoc, 1=Documented, 2=Procedural, 3=Specified, 4=Automated)
   Governance:  G_ (0=Ungoverned, 1=Tracked, 2=Planned, 3=Governed, 4=Auditable)
   

2. Identify the constraining dimension (lowest level)
3. For NEW specs, record baseline as C0/E0/A0/P0/G0
4. Note target maturity profile for this enhancement (what level should each dimension reach?)

Present:

Current Maturity: C_/E_/A_/P_/G_ (effective: L_)
Constraining Dimension: [dimension] at level [N]
Target After Enhancement: C_/E_/A_/P_/G_

Note: This phase is informational — it guides effort allocation but does not gate progression. Skip if spec doesn't exist yet (NEW category without prior version).

Step 3: Phase 1 — Governing Spec Verification

Objective: Read governing spec(s) before modifying anything.

Execute:

1. Identify governing spec(s) for the artifact type:
   • Skill specs → read SKILL_NAMING_CONVENTION_SPEC (in aget/specs/; note: AGET_SKILLS_SPEC is archived)
   • SOPs → read AGET_SOP_SPEC
   • General specs → read AGET_SPEC_FORMAT (if exists)
2. Read each governing spec — extract specific requirements (CAP-xxx-nnn)
3. Verify cross-reference targets in governing spec are not stale:

   # For each referenced file in the governing spec
   test -f "<referenced_path>" && echo "OK" || echo "STALE: <path>"
   

4. If stale targets found, flag for remediation at Phase 5a

Anti-Pattern Check: Decorative Spec Basis

• After reading governing spec, verify you can cite specific CAP requirements
• If you declared a spec basis but can't cite specific requirements → STOP and re-read

Exit Criteria: Governing spec(s) read and cited. Cross-reference targets verified.

Step 4: Phase 2 — Census & Classification

Objective: Inventory all artifacts that need enhancement.

Execute:

1. Enumerate all specs/artifacts in scope
2. For each artifact, read the file to get current version and status (NEVER assert from memory — L611)
3. Identify dependency order
4. Produce census table:

   | Artifact | Current Version | Category | Dependencies | Priority |
   |----------|:---------------:|----------|--------------|:--------:|
   | <spec path> | <from file read> | <category> | <specs it references> | <1-N> |
   

USER CHECKPOINT: Present census table and ask:

Census: <count> artifacts in scope
Dependencies: <dependency chain summary>

Approve census and proceed? (yes/add artifact/remove artifact/abort)

Exit Criteria: All artifacts inventoried. Dependencies mapped. Priority assigned.

Step 5: Phase 3 — Draft/Update Spec

Objective: Write or update the specification content.

Execute:

1. Update spec header (version, status, date)
2. Write requirements in EARS patterns:
   • Ubiquitous: The SYSTEM shall...
   • Conditional: IF condition THEN the SYSTEM shall...
   • Event-driven: WHEN event THEN the SYSTEM shall...
   • Optional: WHERE condition, the SYSTEM should...
   • Prohibited: The SYSTEM shall NOT...
   • Unwanted: artifact shall NOT...
3. Assign unique requirement IDs: R-{DOMAIN}-{NNN}
4. If new vocabulary terms introduced, add SKOS vocabulary section
5. If applicable, use "codify existing behavior" approach (fastest — L622 evidence)

USER CHECKPOINT: Present draft spec content and ask:

Spec: <path>
Version: <current> → <target>
Requirements: <count> total (<new_count> new, <modified_count> modified)

Review spec content. Approve and proceed? (yes/edit/abort)

Exit Criteria: Spec content written. All requirements have IDs and EARS patterns.

Step 6: Phase 4 — Structural Validation

Objective: Verify spec meets structural requirements.

Execute:

1. Check required sections present per governing spec format
2. Check naming conventions
3. Validate EARS pattern compliance for all requirements:

   For each requirement:
   - Has unique R-{DOMAIN}-{NNN} ID? ✓/✗
   - Uses EARS pattern keyword? ✓/✗
   - Pattern type recorded? ✓/✗
   

4. Verify version number follows semantic versioning
5. Run structural validators if available:

   python3 .aget/patterns/sync/validate_spec_compliance.py <spec_path> 2>/dev/null
   

Report results:

Structural Validation: <PASS/FAIL>
  Sections: <count>/<expected> present
  Requirements: <count> with valid EARS patterns
  Naming: <PASS/FAIL>
  Version: <PASS/FAIL>
  Validator: <PASS/FAIL/not available>

Exit Criteria: Spec passes structural validation. No format errors.

Step 7: Phase 5 — Cross-Reference Wiring

Objective: Connect spec to related artifacts with bidirectional traceability.

Phase 5a: Stale Artifact Remediation

Before wiring, verify all targets are current:

For each cross-reference target:
1. File exists? ✓/✗
2. Version/status current? ✓/✗
3. If stale → flag for update before wiring

If stale targets found, present remediation plan before proceeding.

Phase 5b: Primary Cross-Wiring

For each requirement:

1. Link to evidence L-doc(s) — why does this requirement exist?
2. Link to V-test — how is this requirement enforced?
3. Link to related specs (broader/narrower/related)

Produce cross-reference report:

| Requirement | Evidence (L-doc) | Enforcement (V-test) | Related Specs |
|-------------|-----------------|---------------------|---------------|
| R-XXX-001 | L### | V-XXX-001 | SPEC_Y |

Phase 5c: Bidirectional Verification

For each outgoing reference, verify target acknowledges this spec. For each incoming reference, verify this spec acknowledges source.

USER CHECKPOINT: Present cross-reference report and ask:

Cross-References: <count> requirements mapped
Stale targets: <count> (remediated: <count>)
Bidirectional gaps: <count>

Approve wiring and proceed? (yes/fix gaps/abort)

Exit Criteria: All requirements trace to evidence and enforcement. Bidirectional references verified.

Step 8: Phase 6 — Self-Compliance Check

Objective: Verify the enhancement complies with its own specs.

Execute — these checks are MANDATORY (C3 — no skip option):

1. Bootstrapping paradox check (L560):

   • Does the spec enhancement comply with the lessons it references?
   • Does the output comply with its own requirements?

   For each R-requirement in the spec:
   - Does this enhancement process follow this requirement? ✓/✗
   

2. Spec self-compliance:

   • Does the spec meet the format requirements of its governing spec?

3. Vocabulary compliance:

   • Are all terms used consistently with controlled vocabulary?

Report:

Self-Compliance Check:
  Bootstrapping paradox: <PASS/FAIL — details>
  Spec self-compliance: <PASS/FAIL — details>
  Vocabulary compliance: <PASS/FAIL — details>
  Overall: <PASS/FAIL>

USER CHECKPOINT: Present compliance results and ask:

Self-compliance: <PASS/FAIL>
<details of any failures>

Acknowledge results? (acknowledge/fix and re-check/abort)

Exit Criteria: Self-compliance confirmed. No bootstrapping paradox detected.

Step 9: Produce Outputs

Generate final deliverables:

1. Updated/New Spec: The spec file (already written in Phase 3, validated in Phase 4)
2. Cross-Reference Report: From Phase 5b (formatted table)
3. Enhancement Decision Log:

   Enhancement Decision Log:
     Category: <category>
     Governing Spec: <spec> (CAP citations: <list>)
     Census: <count> artifacts
     Requirements: <count> (EARS: <breakdown>)
     Self-Compliance: <PASS/FAIL>
     Completed Phases: <list>
     Skipped Phases: <list with justification>
   

4. Stale Artifact Report: From Phase 5a (if any)

Present summary:

=== /aget-enhance-spec Complete ===

Category: <CATEGORY>
Target: <spec path>
Version: <previous> → <new>
Requirements: <count>
Cross-References: <count> mapped
Self-Compliance: <PASS/FAIL>
Phases Executed: <list>

Outputs:
  - Spec: <path>
  - Cross-Ref Report: <inline or path>
  - Decision Log: <inline>

Constraints

These are INVIOLABLE — you MUST NOT violate these constraints:

1. C1: NEVER skip Phase 1 (Governing Spec Verification)
2. C2: NEVER assert spec state from memory — always read files (L611)
3. C3: NEVER skip Phase 6 (Self-Compliance Check) — no skip option exists
4. C4: NEVER execute deployment phases 7-10 (template, tooling, fleet, post-deploy)
5. C5: ALWAYS present user checkpoint before proceeding past Phases 0, 2, 3, 5, 6
6. C6: ALWAYS produce cross-reference report as output
7. C7: ALWAYS cite governing spec requirements (CAP-xxx-nnn) in deliverables
8. C8: ALWAYS use EARS patterns for requirements
9. C9: ALWAYS assign unique R-{DOMAIN}-{NNN} IDs to requirements

Anti-Pattern Detection

The skill actively checks for these anti-patterns:

Related Skills

• /aget-create-project — Create project plan for enhancement work
• /aget-propose-skill — Propose new skills (used in this project at G3)
• /aget-record-lesson — Capture lessons discovered during enhancement
• /aget-review-project — Review enhancement project progress
• /aget-study-topic — Research topic before enhancing

Step 10: Skill Completion Signal (D71 Layer 3)

Purpose: Make skill execution completeness structurally visible. If this signal is absent, the skill execution is incomplete.

The skill MUST output this signal as the LAST section of the report:

## Skill Completion Signal
**Self-Compliance**: PASS | FAIL (items: [list])
**Cross-References**: PASS (N mapped) | SKIP (justification)
**Phases Completed**: 0→1→2→3→4→5→6→9→10

If Phase 6 (Self-Compliance Check) was not executed, the signal MUST report FAIL. Per C3, Phase 6 has no skip option.

Enforcement: Strict (ADR-008, D71). Signal absence = incomplete execution.

Traceability

aget-enhance-spec v1.1.0 Category: Governance ADR-008 Position: Generator (step 3 of Advisory → Strict → Generator) "Five plans, three agents, one skill."