VELA Enables Lazy Architects
A document-driven harness specification repository for AI coding agents.
Language: English · 简体中文
- VELA
VELA is a harness-builder specification project.
Its purpose is not to ship a prebuilt harness package directly. Instead, it provides a strict BUILDER specification so that an agent can generate the full VELA Harness runtime in a stable and reproducible way.
In other words:
- This repository primarily defines how VELA Harness should be generated.
- The actual runtime harness is generated by an agent from the BUILDER.
- The README explains the intent, usage, and output structure for humans.
The current repository structure is:
README.md
README_zh.md
VELA_HARNESS_BUILDER.md
assets/
└── vela-logo.svg
Where:
README.md: English documentation.README_zh.md: Simplified Chinese documentation.VELA_HARNESS_BUILDER.md: the core build specification that defines how to generateAGENTS.md,CLAUDE.md, and.vela/.assets/vela-logo.svg: project logo.
This repository does not upload a prebuilt harness package.
That means the repository normally does not include:
AGENTS.md
CLAUDE.md
.vela/
Why:
- Single source of truth: the
BUILDERstays the only authoritative generation source. - Reproducibility: anyone can regenerate the full harness from the same BUILDER.
- Less drift: generated artifacts can drift away from the specification, while the BUILDER remains authoritative.
- Cleaner iteration: when rules change, only the BUILDER and the READMEs need to be updated.
VELA is built around five design ideas:
- Documentation before code.
- Goals before boundaries; boundaries before architecture; architecture before development.
- North Star document v0.0.1 is the only valid entry input.
- When boundaries are unclear, the agent must use a question protocol instead of making things up.
- Once development starts, software code must converge under
project/.
This makes VELA more like a development process constraint layer than a normal template repository.
Build the harness according to VELA_HARNESS_BUILDER.md.
Clone or download the repository and obtain:
README.md
README_zh.md
VELA_HARNESS_BUILDER.md
assets/vela-logo.svg
Provide VELA_HARNESS_BUILDER.md to an AI coding agent that supports file input, and explicitly ask it to:
- generate the full VELA Harness according to the BUILDER,
- generate only the files defined by the specification,
- perform the required self-checks,
- and stop after the Builder stage rather than entering project development.
According to the BUILDER, the generated output should be:
AGENTS.md
CLAUDE.md
.vela/
Important: these are generated outputs, not files that this repository ships by default.
After generation, place the following into the root of your target project workspace:
AGENTS.md
CLAUDE.md
.vela/
Then let Codex or Claude Code run inside that workspace.
According to the BUILDER, the generated VELA Harness runtime contains:
AGENTS.md
CLAUDE.md
.vela/
├── SKILL.md
├── README.md
├── harness.yaml
├── CHANGELOG.md
├── rules/
├── templates/
├── schemas/
├── checklists/
└── extensions/
Key responsibilities:
AGENTS.md: Codex discovery adapter that delegates to.vela/SKILL.md.CLAUDE.md: Claude Code discovery adapter that delegates to.vela/SKILL.md..vela/SKILL.md: the canonical runtime entrypoint..vela/harness.yaml: the highest authority for structure and file inventory..vela/rules/: stage rules, protocol rules, and quality rules..vela/templates/: document templates..vela/schemas/: structural constraints; higher priority than templates..vela/checklists/: self-check and stage-completion checklists.
The only valid runtime input entry for VELA is a user-provided North Star document v0.0.1.
Minimum recommended shape:
# North Star Document v0.0.1
## 1. Project Goal
## 2. Target Users
## 3. Core Usage Scenarios
## 4. MVP Boundary
## 5. Non-goals
## 6. Technical / Platform Constraints
## 7. Core Feature Directions
## 8. Open Questions
## 9. Decision Records
## 10. Changelog- For Codex: read
AGENTS.mdat the workspace root - For Claude Code: read
CLAUDE.mdat the workspace root
Both must continue to delegate to .vela/SKILL.md. They must not branch into a second rule system.
VELA does not allow jumping straight into coding. It requires a fixed stage progression until TODO.md can be generated and development can be executed legally.
VELA uses a fixed stage machine:
| Stage | Meaning |
|---|---|
| S0 | Entry validation |
| S1 | North Star completion |
| S2 | Frontend / backend boundary discovery |
| S3 | System boundary confirmation |
| S4 | System boundary document generation |
| S5 | Architecture specification generation |
| S6 | TODO execution track generation |
| S7 | Development execution |
| S8 | Conflict resolution |
Stages must not be skipped. README must not be treated as the execution rule source, and development must not start before boundary and architecture work is complete.
- The runtime entry input must be a user-provided North Star document
v0.0.1. - The agent must not infer project goals from code, the project name, or the tech stack.
- When boundaries are unclear, the question protocol must be used.
- Each question should include recommended options.
- The user may respond with “use all recommended options”.
- High-risk boundaries require second confirmation.
TODO.mdis the only execution track for project development.- Each TODO must have its own plan.
- By default, only one current TODO is advanced at a time.
- The Builder stage must not create
project/. - During runtime, all generated or modified software code must stay under
project/at the workspace root. docs/,TODO.md, decision records, boundary documents, and architecture specs are not part of the software code root.
AGENTS.mdandCLAUDE.mdmust live at the workspace root.- They are only default discovery adapters.
- The real canonical entrypoint is always
.vela/SKILL.md.
From highest to lowest, VELA can be understood as:
.vela/harness.yaml: highest authority for structure and file inventory..vela/SKILL.md: highest authority for runtime entry behavior..vela/rules/stages/: stage-execution rules..vela/rules/protocols/: cross-stage protocol rules..vela/rules/quality/: quality acceptance rules..vela/schemas/: structural constraints, higher than templates..vela/templates/: formatting only, not rule authority.AGENTS.md/CLAUDE.md: adapter entrypoints, not core rule authorities..vela/README.md: human-facing explanation, not an execution rule source.
Because this repository is meant to maintain the build specification, not a generated artifact that may drift away from that specification.
You do not copy the whole repository as-is. Instead, first let an agent generate the harness from VELA_HARNESS_BUILDER.md, and then place the generated:
AGENTS.md
CLAUDE.md
.vela/
into your target workspace.
No. The README explains the project to humans. The true rule sources are the BUILDER and, after generation, .vela/SKILL.md, .vela/rules/, .vela/schemas/, and .vela/checklists/.
It is for people who want to constrain AI coding agents into a stable, document-first, stage-driven development workflow.
For the Chinese version, see README_zh.md.