arggon-harness 0.1.0

package/src/commands/spec-init.md

@@ -0,0 +1,6 @@
+---
+description: Initialize the spec/ directory structure for a new project
+---
+
+Load the spec-init skill and follow its instructions.
+Arguments: $ARGUMENTS

package/src/commands/spec-onboard.md

@@ -0,0 +1,6 @@
+---
+description: Guided onboarding tutorial for spec-native
+---
+
+Load the spec-onboard skill and follow its instructions.
+Arguments: $ARGUMENTS

package/src/commands/spec-status.md

@@ -0,0 +1,6 @@
+---
+description: Show status of spec changes
+---
+
+Load the spec-status skill and follow its instructions.
+Arguments: $ARGUMENTS

package/src/commands/spec-sync.md

@@ -0,0 +1,6 @@
+---
+description: Sync delta specs to main specs
+---
+
+Load the spec-sync skill and follow its instructions.
+Arguments: $ARGUMENTS

package/src/schemas/hybrid.yaml

@@ -0,0 +1,144 @@
+name: hybrid
+version: 1
+description: Combined workflow - spec-driven planning with TDD implementation
+
+artifacts:
+  - id: proposal
+    generates: proposal.yaml
+    description: Change proposal with capabilities and acceptance criteria
+    template: proposal.yaml
+    instruction: |
+      Create a proposal that combines:
+      1. Capability-based thinking (what behaviors?)
+      2. Testable acceptance criteria (how to verify?)
+      
+      For each capability:
+      - Define the behavior
+      - List acceptance criteria
+      - Identify test interfaces
+    requires: []
+
+  - id: specs
+    generates: specs/*.yaml
+    description: Specifications with scenarios and verification
+    template: spec.yaml
+    instruction: |
+      Create specs that are both:
+      - Behavior-focused (like spec-driven)
+      - Test-oriented (like TDD)
+      
+      For each requirement:
+      - Use clear requirement IDs
+      - Write Given/When/Then scenarios
+      - Add verify blocks with testable assertions
+      - Specify test interface when relevant
+    requires: [proposal]
+
+  - id: design-tech
+    generates: design-tech.yaml
+    description: Technical design with testability considerations
+    template: design-tech.yaml
+    instruction: |
+      Create a design that covers:
+      1. Architecture decisions (spec-driven style)
+      2. Testability decisions (TDD style)
+      3. Implementation approach
+      
+      Balance between:
+      - High-level architecture
+      - Test-friendly interfaces
+      - Practical implementation concerns
+    requires: [specs]
+
+  - id: design-wireframe
+    generates: design-wireframe.yaml
+    description: Page wireframes with layouts, component placements, user flows, and annotations
+    template: design-wireframe.yaml
+    optional: true
+    instruction: |
+      Create wireframe specifications for the change's UI pages.
+      
+      Only create this artifact if the change involves user-facing UI changes.
+      If the change is backend-only, infrastructure, or has no visual component,
+      skip this artifact.
+      
+      Include:
+      1. Pages - list all UI pages/screens with their layout regions
+      2. Layout - define regions (header, sidebar, main, footer) with ordering
+      3. Components - place UI components (buttons, cards, inputs, etc.) in regions with positions and sizes
+      4. Flows - document user navigation paths between pages
+      5. Annotations - add notes about constraints, edge cases, design decisions
+      
+      Use kebab-case for page IDs, component IDs, and flow IDs.
+      Position coordinates use a 12-column grid system (0-11).
+      
+      The optional html_preview flag generates a visual wireframe preview.
+    requires: [design-tech]
+
+  - id: design-hifi
+    generates: design-hifi.yaml
+    description: High-fidelity design system specification with color, typography, spacing, and components
+    template: design-hifi.yaml
+    optional: true
+    instruction: |
+      Create a high-fidelity design system specification.
+      
+      Only create this artifact if the change requires visual design decisions.
+      Can be created directly after wireframes, or skipped if only wireframes are needed.
+      
+      Include:
+      1. Color Palette - primary, secondary, accent, neutral, semantic, and surface colors with hex values
+      2. Typography - font families, type scale with sizes/weights/line-heights, hierarchy roles
+      3. Spacing - base unit and spacing scale
+      4. Component Library - button, card, input, and navigation variants with states
+      5. Breakpoints - responsive breakpoints with column counts and rules
+      
+      Use hex format (#RRGGBB) for all colors.
+      The type scale should cover h1-h6, body, caption, and small roles.
+      
+      The optional html_preview flag generates a visual style guide preview.
+    requires: [design-wireframe]
+
+  - id: tasks
+    generates: tasks.yaml
+    description: Tasks organized by feature with optional TDD phases
+    template: tasks.yaml
+    instruction: |
+      Organize tasks by feature/capability.
+      
+      For each feature, you can:
+      - Use standard tasks (implement, test, verify)
+      - OR use TDD phases (red, green, refactor)
+      
+      Use tdd_phase field when TDD is appropriate:
+      - Complex logic that benefits from test-first
+      - Critical paths that need high confidence
+      - Areas with unclear requirements
+      
+      Use standard tasks for:
+      - Simple CRUD operations
+      - Configuration changes
+      - Documentation updates
+      
+      Mix and match based on what makes sense.
+    requires: [specs, design-tech]
+
+apply:
+  requires: [tasks]
+  tracks: tasks.yaml
+  instruction: |
+    Implement tasks in dependency order.
+    
+    For TDD tasks (with tdd_phase):
+    - Follow strict RED-GREEN-REFACTOR cycle
+    - Write test first, confirm failure
+    - Implement minimal code, confirm pass
+    - Refactor, run all tests
+    
+    For standard tasks:
+    - Implement the change
+    - Write/update tests
+    - Verify acceptance criteria
+    - Update task status
+    
+    Adapt your approach to the task type.

package/src/schemas/spec-driven.yaml

@@ -0,0 +1,155 @@
+name: spec-driven
+version: 1
+description: Standard spec-driven workflow with proposal, specs, design, and tasks
+
+artifacts:
+  - id: proposal
+    generates: proposal.yaml
+    description: Change proposal with why, what, and impact
+    template: proposal.yaml
+    instruction: |
+      Create a proposal that explains:
+      1. WHY this change is needed (problem statement)
+      2. WHAT will change (new/modified capabilities)
+      3. IMPACT on existing code (files, APIs, dependencies)
+      
+      Be specific about capabilities - each becomes a spec file.
+      Use kebab-case for capability IDs.
+    requires: []
+
+  - id: specs
+    generates: specs/*.yaml
+    description: Delta specifications for each capability
+    template: spec.yaml
+    instruction: |
+      Create one spec file per capability listed in the proposal.
+      
+      For NEW capabilities:
+      - Use op: add for each requirement
+      - Each requirement must have at least one scenario
+      - Scenarios use given/when/then format
+      - Add verify blocks for testable assertions
+      
+      For MODIFIED capabilities:
+      - Read the existing spec from spec/main/<capability>.yaml
+      - Use op: modify with the complete updated requirement
+      - Use op: add for new requirements
+      - Use op: remove for deprecated requirements
+      
+      Use SHALL/MUST for normative requirements.
+      Keep requirements focused - one behavior per requirement.
+    requires: [proposal]
+
+  - id: design-tech
+    generates: design-tech.yaml
+    description: Technical design with architecture decisions
+    template: design-tech.yaml
+    instruction: |
+      Create a design document that explains HOW to implement the change.
+      
+      Include:
+      1. Context - current state and constraints
+      2. Goals - what this design achieves
+      3. Non-goals - what's explicitly out of scope
+      4. Decisions - key technical choices with alternatives considered
+      5. Risks - known issues and mitigations
+      
+      Only create design-tech.yaml if the change:
+      - Crosses multiple services/modules
+      - Introduces new dependencies
+      - Has security/performance/migration complexity
+      - Benefits from technical decisions before coding
+      
+      For simple changes, you can skip this artifact.
+    requires: [proposal]
+
+  - id: design-wireframe
+    generates: design-wireframe.yaml
+    description: Page wireframes with layouts, component placements, user flows, and annotations
+    template: design-wireframe.yaml
+    optional: true
+    instruction: |
+      Create wireframe specifications for the change's UI pages.
+      
+      Only create this artifact if the change involves user-facing UI changes.
+      If the change is backend-only, infrastructure, or has no visual component,
+      skip this artifact.
+      
+      Include:
+      1. Pages - list all UI pages/screens with their layout regions
+      2. Layout - define regions (header, sidebar, main, footer) with ordering
+      3. Components - place UI components (buttons, cards, inputs, etc.) in regions with positions and sizes
+      4. Flows - document user navigation paths between pages
+      5. Annotations - add notes about constraints, edge cases, design decisions
+      
+      Use kebab-case for page IDs, component IDs, and flow IDs.
+      Position coordinates use a 12-column grid system (0-11).
+      
+      The optional html_preview flag generates a visual wireframe preview.
+    requires: [design-tech]
+
+  - id: design-hifi
+    generates: design-hifi.yaml
+    description: High-fidelity design system specification with color, typography, spacing, and components
+    template: design-hifi.yaml
+    optional: true
+    instruction: |
+      Create a high-fidelity design system specification.
+      
+      Only create this artifact if the change requires visual design decisions.
+      Can be created directly after wireframes, or skipped if only wireframes are needed.
+      
+      Include:
+      1. Color Palette - primary, secondary, accent, neutral, semantic, and surface colors with hex values
+      2. Typography - font families, type scale with sizes/weights/line-heights, hierarchy roles
+      3. Spacing - base unit and spacing scale
+      4. Component Library - button, card, input, and navigation variants with states
+      5. Breakpoints - responsive breakpoints with column counts and rules
+      
+      Use hex format (#RRGGBB) for all colors.
+      The type scale should cover h1-h6, body, caption, and small roles.
+      
+      The optional html_preview flag generates a visual style guide preview.
+    requires: [design-wireframe]
+
+  - id: tasks
+    generates: tasks.yaml
+    description: Implementation task list with dependencies
+    template: tasks.yaml
+    instruction: |
+      Break the implementation into concrete tasks.
+      
+      Each task must:
+      - Have a unique ID (t1, t2, t3, ...)
+      - Belong to a group (Database, Auth, API, UI, etc.)
+      - List dependencies (other task IDs)
+      - Estimate complexity (low/medium/high)
+      - Estimate time in minutes
+      - Reference specs (capability/requirement)
+      - List affected files
+      - Define acceptance criteria
+      
+      Order tasks by dependency (what must be done first?).
+      Keep tasks small enough to complete in one session.
+      Each task should be independently verifiable.
+    requires: [specs, design-tech]
+
+apply:
+  requires: [tasks]
+  tracks: tasks.yaml
+  instruction: |
+    Implement tasks in dependency order.
+    
+    For each task:
+    1. Read the task details and acceptance criteria
+    2. Read referenced specs for context
+    3. Implement the changes
+    4. Verify acceptance criteria are met
+    5. Update task status to "done"
+    
+    Pause if:
+    - Task is unclear (ask for clarification)
+    - Design issue discovered (suggest design update)
+    - Error or blocker (report and wait)
+    
+    Keep changes minimal and scoped to the task.

package/src/schemas/tdd.yaml

@@ -0,0 +1,203 @@
+name: tdd
+version: 1
+description: Test-driven development with RED-GREEN-REFACTOR vertical slices
+
+artifacts:
+  - id: proposal
+    generates: proposal.yaml
+    description: Change proposal with testable acceptance criteria
+    template: proposal.yaml
+    instruction: |
+      Create a proposal focused on BEHAVIORS to implement.
+      
+      For each capability:
+      - Define the behavior in testable terms
+      - List acceptance criteria that can be verified
+      - Identify the public interface to test through
+      
+      Use language like:
+      "The system SHALL allow users to..."
+      "When X happens, the system MUST..."
+    requires: []
+
+  - id: specs
+    generates: specs/*.yaml
+    description: Requirements with Gherkin scenarios and verification
+    template: spec.yaml
+    instruction: |
+      Create specs with a TDD focus:
+      
+      For each requirement:
+      - Use REQ-N naming (REQ-1, REQ-2, ...)
+      - Write scenarios in Gherkin format (Given/When/Then)
+      - Specify "Test through: <interface>" for each requirement
+      - Add verify blocks with executable test code
+      
+      Example:
+      ```yaml
+      operations:
+        - op: add
+          requirement:
+            id: REQ-1
+            description: The system SHALL export data as CSV
+            scenarios:
+              - id: export-csv
+                given: [user has existing data]
+                when: [export is called with format "csv"]
+                then: [returns CSV file with all data]
+                verify:
+                  - type: assertion
+                    code: "result.format === 'csv' && result.data.length > 0"
+      ```
+      
+      Each scenario maps directly to a test case.
+    requires: [proposal]
+
+  - id: design-tech
+    generates: design-tech.yaml
+    description: Technical design with testability decisions
+    template: design-tech.yaml
+    instruction: |
+      Create a design focused on TESTABILITY:
+      
+      Include:
+      1. Testability Decisions
+         - How to inject dependencies
+         - What interfaces to test through
+         - Mocking strategy
+      2. Interface Contracts
+         - Public APIs to test through
+         - Input/output types
+         - Error conditions
+      3. Test Architecture
+         - Test file structure
+         - Test utilities needed
+         - Integration vs unit test boundaries
+      
+      Design principles:
+      - Accept dependencies as parameters
+      - Return results, don't produce side effects
+      - Keep surface area small
+    requires: [specs]
+
+  - id: design-wireframe
+    generates: design-wireframe.yaml
+    description: Page wireframes with layouts, component placements, user flows, and annotations
+    template: design-wireframe.yaml
+    optional: true
+    instruction: |
+      Create wireframe specifications for the change's UI pages.
+      
+      Only create this artifact if the change involves user-facing UI changes.
+      If the change is backend-only, infrastructure, or has no visual component,
+      skip this artifact.
+      
+      Include:
+      1. Pages - list all UI pages/screens with their layout regions
+      2. Layout - define regions (header, sidebar, main, footer) with ordering
+      3. Components - place UI components (buttons, cards, inputs, etc.) in regions with positions and sizes
+      4. Flows - document user navigation paths between pages
+      5. Annotations - add notes about constraints, edge cases, design decisions
+      
+      Use kebab-case for page IDs, component IDs, and flow IDs.
+      Position coordinates use a 12-column grid system (0-11).
+      
+      The optional html_preview flag generates a visual wireframe preview.
+    requires: [design-tech]
+
+  - id: design-hifi
+    generates: design-hifi.yaml
+    description: High-fidelity design system specification with color, typography, spacing, and components
+    template: design-hifi.yaml
+    optional: true
+    instruction: |
+      Create a high-fidelity design system specification.
+      
+      Only create this artifact if the change requires visual design decisions.
+      Can be created directly after wireframes, or skipped if only wireframes are needed.
+      
+      Include:
+      1. Color Palette - primary, secondary, accent, neutral, semantic, and surface colors with hex values
+      2. Typography - font families, type scale with sizes/weights/line-heights, hierarchy roles
+      3. Spacing - base unit and spacing scale
+      4. Component Library - button, card, input, and navigation variants with states
+      5. Breakpoints - responsive breakpoints with column counts and rules
+      
+      Use hex format (#RRGGBB) for all colors.
+      The type scale should cover h1-h6, body, caption, and small roles.
+      
+      The optional html_preview flag generates a visual style guide preview.
+    requires: [design-wireframe]
+
+  - id: tasks
+    generates: tasks.yaml
+    description: Vertical slice tasks in RED-GREEN-REFACTOR cycles
+    template: tasks.yaml
+    instruction: |
+      Organize tasks as VERTICAL SLICES - one behavior at a time.
+      
+      For each behavior (requirement):
+      1. RED phase tasks:
+         - Write failing test
+         - Run test to confirm failure
+      2. GREEN phase tasks:
+         - Write minimal implementation
+         - Run test to confirm pass
+      3. REFACTOR phase tasks:
+         - Clean up code
+         - Run all tests
+      
+      Use tdd_phase field: red, green, refactor
+      
+      Example:
+      ```yaml
+      tasks:
+        - id: t1
+          group: Export Feature
+          description: Write failing test for CSV export
+          tdd_phase: red
+          depends_on: []
+          spec_refs: [export/REQ-1]
+        - id: t2
+          group: Export Feature
+          description: Implement CSV export to pass test
+          tdd_phase: green
+          depends_on: [t1]
+          spec_refs: [export/REQ-1]
+        - id: t3
+          group: Export Feature
+          description: Refactor export code
+          tdd_phase: refactor
+          depends_on: [t2]
+          spec_refs: [export/REQ-1]
+      ```
+      
+      NEVER batch all RED tasks together.
+      Complete the full cycle for one behavior before starting the next.
+    requires: [specs, design-tech]
+
+apply:
+  requires: [tasks]
+  tracks: tasks.yaml
+  instruction: |
+    Implement using strict TDD cycle:
+    
+    For each behavior:
+    1. RED: Write the failing test FIRST
+       - Run the test
+       - Confirm it fails (not passes!)
+    2. GREEN: Write minimal code to pass
+       - No extra features
+       - No anticipating future tests
+       - Run the test
+       - Confirm it passes
+    3. REFACTOR: Clean up
+       - Remove duplication
+       - Improve naming
+       - Run ALL tests
+       - Confirm nothing broke
+    
+    Then move to the next behavior.
+    
+    If a test is hard to write, the design needs work.
+    If you're stuck, go back to the design artifact.