arggon-harness

Spec-driven SDLC workflow for OpenCode

Overview

arggon-harness is an OpenCode plugin that enforces a structured, traceable workflow for all code changes. Every modification — feature, bugfix, refactor — flows through five mandatory phases: explore → propose → apply → verify → archive.

The goal is to replace ad-hoc coding with spec-driven development. Each change produces a trail of YAML artifacts (proposal, specs, design, tasks) that are integrity-verified and traceable from requirement to implementation.

The harness ships as an OpenCode plugin with 13 custom tools, 10 workflow skills, 9 slash commands, and a CLI init script (harness-init) that sets up skills, commands, config, and the spec directory in your project.

Quick Start

# In your project directory:
npx arggon-harness init

This single command:

1. Sets up skills, commands, and agents in .opencode/
2. Creates/updates .opencode/opencode.json with the plugin and permissions
3. Optionally initializes a spec/ directory
4. Checks the OpenCode plugin cache and refreshes it if stale

Then open your project in OpenCode — the plugin loads automatically.

For npm-installed projects:

npm install arggon-harness
npx harness-init

For development from source:

git clone https://github.com/Arggon/harness.git
cd harness
npm install
npm test

For Contributors

git clone https://github.com/Arggon/harness.git
cd harness
npm install

# Run all tests
npm test

# Run specific test suites
npm run test:engine       # Engine unit tests
npm run test:tools        # Tool tests
npm run test:hooks        # Hook tests
npm run test:integration  # Integration tests

# Build plugin after changes
cd src/plugin && bun run build

The harness is self-hosting — it uses its own spec-driven workflow for development.

Project Structure

After building and configuring in your project:

your-project/
├── .opencode/
│   ├── opencode.json          # Plugin, agents, permissions
│   ├── skills/                # 10 workflow skills
│   │   ├── spec-explore/
│   │   ├── spec-propose/
│   │   ├── spec-apply/
│   │   ├── spec-verify/
│   │   ├── spec-archive/
│   │   ├── spec-sync/
│   │   ├── spec-status/
│   │   ├── spec-init/
│   │   ├── spec-onboard/
│   │   └── playwright-cli/
│   └── commands/              # 9 slash commands
│       ├── spec-explore.md
│       ├── spec-propose.md
│       └── ...
├── spec/                      # Spec data (created by workflow)
│   ├── config.yaml            # Project context and rules
│   ├── registry.yaml          # Change index
│   ├── main/                  # Canonical merged specs
│   ├── changes/               # Active changes
│   │   └── <change-name>/
│   │       ├── meta.yaml
│   │       ├── proposal.yaml
│   │       ├── specs/
│   │       ├── design.yaml
│   │       ├── tasks.yaml
│   │       └── .verify/
│   └── archive/               # Archived changes

Source Layout (for contributors)

harness/
├── src/
│   ├── plugin/                # OpenCode plugin
│   │   ├── index.ts           # Entry point
│   │   ├── engine/            # Core engine (pure TypeScript)
│   │   ├── tools/             # 13 tool implementations
│   │   └── hooks/             # System prompt + workflow gate hooks
│   ├── schemas/               # Workflow schemas (spec-driven, ui-driven, tdd, hybrid)
│   ├── templates/             # Per-schema artifact templates
│   │   ├── spec-driven/       # proposal.yaml, spec.yaml, design-tech.yaml, tasks.yaml, schema.yaml
│   │   ├── ui-driven/         # design-html.html, design-wireframe.yaml, design-hifi.yaml, schema.yaml
│   │   ├── tdd/               # proposal.yaml, spec.yaml, design-tech.yaml, tasks.yaml, schema.yaml
│   │   ├── hybrid/            # proposal.yaml, spec.yaml, design-tech.yaml, tasks.yaml, schema.yaml
│   │   ├── config.yaml        # Shared init template
│   │   └── registry.yaml      # Shared init template
│   ├── skills/                # Skill definitions
│   ├── commands/              # Command wrappers
│   └── init.ts                # CLI init script
├── config/
│   └── default-opencode.json  # Config template
└── test/                      # Test suite

The Workflow

Every code change follows five mandatory phases enforced by the orchestrator agent:

| Phase | Command | What Happens | |-------|---------|--------------| | Explore | /spec-explore | Investigate the problem, read code, clarify requirements. The orchestrator handles this phase directly. | | Propose | /spec-propose | Create a spec change with proposal, delta specs, design, and task checklist — all as YAML artifacts. | | Apply | /spec-apply | Implement tasks one at a time, respecting dependencies. Each task is tracked and marked complete. | | Verify | /spec-verify | 5-dimension verification: integrity, compliance, tasks, coherence, regression. | | Archive | /spec-archive | Sync delta specs to main specs, move change to spec/archive/, preserve audit trail. |

No shortcuts. No "quick fixes" that skip the workflow. The orchestrator agent enforces this for every change, even when the user says "just fix it."

What You Get

Plugin — 13 Tools

| Tool | Purpose | |------|---------| | spec_change_new | Create a new spec change | | spec_change_status | Show artifact and task status | | spec_change_list | List all active changes | | spec_change_archive | Archive a completed change | | spec_artifact_instr | Get artifact instructions and templates | | spec_validate | Validate artifact structure and integrity | | spec_verify | Run 5-dimension verification | | spec_specs_apply | Apply delta specs to main specs | | spec_task_progress | Track and update task completion | | spec_integrity_check | SHA-256 integrity verification | | spec_schema_list | List available workflow schemas | | spec_registry_update | Update the change registry | | spec_init | Initialize spec directory structure |

Skills — 10

| Skill | Description | |-------|-------------| | spec-explore | Thinking partner for investigating problems and clarifying requirements | | spec-propose | Generate a complete change proposal with all artifacts in one step | | spec-apply | Implement tasks from a spec change | | spec-verify | 5-dimension verification of implementation | | spec-archive | Archive completed changes and sync delta specs | | spec-sync | Sync delta specs to main without archiving | | spec-status | Show artifact completion, task progress, and verification state | | spec-init | Initialize the spec/ directory structure | | spec-onboard | Guided onboarding tutorial through a complete workflow cycle | | playwright-cli | Browser automation for testing |

Commands — 9

Slash commands that map to skills: /spec-explore, /spec-propose, /spec-apply, /spec-verify, /spec-archive, /spec-sync, /spec-status, /spec-init, /spec-onboard.

Schemas — 4

| Schema | Use Case | |--------|----------| | spec-driven | Default. Specs first, then implementation. | | ui-driven | Frontend/UI work with design-first artifacts (extends spec-driven). Requires visual design HTML, wireframes, and a design system before implementation. | | tdd | Test-driven. Write tests before implementation. RED→GREEN→REFACTOR cycles per behavior. | | hybrid | Combine spec-driven and TDD approaches. Mix standard and TDD-phase tasks per capability. |

Each schema has its own template directory at src/templates/<schema>/ with a schema.yaml manifest that describes the workflow, artifacts, and dependency order. Schemas that extend another schema (e.g., ui-driven extends spec-driven) inherit parent templates via chain-based resolution.

Configuration

When you run harness-init, it generates .opencode/opencode.json automatically:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["arggon-harness"],
  "default_agent": "orchestrator",
  "permission": {
    "spec_change_new": "allow",
    ...
  }
}

The plugin can be referenced as:

• "arggon-harness" — resolved via npm/OpenCode plugin system (auto-downloaded and cached)
• "node_modules/arggon-harness/src/plugin" — local npm install (avoids global cache)
• "/absolute/path/to/harness/src/plugin" — development from source

The harness-init command also manages the OpenCode plugin cache: on each run, it compares the running package version against the cached version, and clears stale cache entries to ensure the plugin always loads fresh.

If opencode.json already exists, entries are merged without overwriting existing config.

Customization

Edit .opencode/opencode.json after setup to:

• Change the model for any agent
• Adjust permissions
• Add custom agents
• Modify agent prompts

Optional: codebase-memory-mcp

codebase-memory-mcp is an MCP server that builds a persistent knowledge graph of your codebase, enabling structural queries instead of expensive grep/glob operations. Agents can search for functions, trace callers, read source snippets, and query architecture — making code exploration up to 99% faster.

Installation

When you run harness-init, it asks whether to install codebase-memory-mcp. Accept to install it automatically:

npx arggon-harness init

Or install manually:

curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash
codebase-memory-mcp index --path .

After installation, the MCP server is configured in .opencode/opencode.json and automatically enabled in OpenCode.

MCP Tools

The knowledge graph provides 14 MCP tools, accessible as codebase-memory-mcp_<toolname>:

| Tool | Purpose | |------|---------| | search_graph | Find functions, classes, routes by pattern | | trace_path | Trace callers or callees of a function | | get_code_snippet | Read specific function or class source code | | query_graph | Run Cypher queries for complex patterns | | get_architecture | High-level project summary with layers and hotspots | | search_code | Full-text code search | | index_repository | Re-index the project's codebase graph | | index_status | Check when the graph was last indexed | | detect_changes | Detect code changes since last index | | list_projects | List all indexed projects | | delete_project | Remove a project from the graph | | get_graph_schema | Show the graph node/edge schema | | manage_adr | Manage architecture decision records | | ingest_traces | Ingest trace data into the graph |

Re-indexing

After significant code changes, re-index the graph:

codebase-memory-mcp index --path .

Or use the built-in /cbm-index-repo skill in OpenCode.

Requirements

• Node.js >= 18
• OpenCode installed
• TypeScript ESM project (for plugin development)

License

MIT