agent-setup

How it works

agent-setup comes down to two commands. bootstrap.sh installs the skills and templates once into ~/.claude/ and ~/.codex/. Then, inside a repo, /init-project ./vision.md generates the workspace: agents, workflows, sprints, engineering standards and a state.json. On the Codex side, the same skill is called $init-project.

Work then starts sprint by sprint. /sprint 001 US-001 reads the task in sprint-001.md, infers the workflow from its Workflow: field and chains the agents. Each stage writes an artefact to .project/workflows/<run-id>/. The task’s checkbox is only ticked after the acceptance criteria have been explicitly checked.

Roles are Markdown files: product-owner, analyst, designer, test-writer, developer, qa-reviewer, tech-lead. Each has its definition and its memory. You can add your own under agent-setup/agents/specialized/ and compose them on the fly, for example /run-workflow analyst-tech-lead.

The last piece, added in May, is vault mode. The migrate skill moves the vision, sprints, agents and workflows into a shared Obsidian vault, with a backup before it touches the repo.

Under the hood

Since v1.11, development is split into red-green-refactor across two roles. The test-writer writes the tests and must see them fail for the right reason. The developer then writes the minimal code to make them pass. The qa-reviewer returns PASS or FAIL, and the tech-lead writes the final summary. That split is where shipyard’s rule comes from: the reviewer checks that tests were not weakened.

## Stage 3a - Red (write the failing test)
Agent: [[agents/test-writer/agent|test-writer]]
Inputs:
- `.project/workflows/<run-id>/01-analyze.md`
- `.project/workflows/<run-id>/02-design.md`
- `agent-setup/spec/engineering-standards.md` §11
Outputs:
- `.project/workflows/<run-id>/03a-red.md`
Pass:
- At least one test exists per acceptance criterion
- Every new test was run via `run-tests` (`expect-fail` mode) and observed to fail for the right reason
- Verbatim failure output is captured in the artifact
- No production code was written or modified
- Test committed alone with a `test:` Conventional Commit
OnFailure:
- Stop and document which acceptance criterion could not be expressed as a failing test

The Pass conditions are written for an agent, not a human: failure output copied verbatim, no production code touched, a standalone test: commit. The [[…]] links are for the Obsidian vault.

The install can be checked without writing anything, here against a demo folder:

What I take away

• Two CLIs were a fixed cost. Even with skills merged into a single file, there were two installs, two call syntaxes (/sprint and $sprint) and the MCP config twice, in .mcp.json and .codex/config.toml. shipyard went with Claude Code only so it could push autonomy further.
• Structured Markdown holds up. Agent / Inputs / Outputs / Pass / OnFailure fields are enough to make a workflow checkable. shipyard took the renderer, templates, roles and state.json as they were.
• There was still a human in the loop. I started every sprint and every workflow, and chaining the stages relied on the model reading the skill. That is exactly what shipyard replaces with a deterministic script.