Project Harness Blueprint

Project Harness Blueprint

Turn an incomplete project description into a concrete working system for future delivery. Default to the smallest harness that can succeed, and add complexity only when there is a clear failure mode to address.

When To Use

Use this skill when the user wants any of the following:

• a harness blueprint before writing product code
• a repo and docs operating model for a new project
• agent roles, sprint contracts, or evaluator design
• a reusable project intake template
• guidance on how to describe a project so Codex can scaffold the workflow

Do not use this skill for normal feature implementation inside an already-operating project unless the user is explicitly redesigning the project workflow.

Input Model

Gather these facts from the user request when available:

• project one-liner
• target users and primary jobs
• first-stage scope
• core features
• non-goals
• acceptance criteria
• technical constraints
• project stage: POC, MVP, internal tool, or production
• desired automation level
• desired blueprint style: Lean, Standard, or Production-Ready

If some inputs are missing, make reasonable assumptions and label them clearly. Ask follow-up questions only when the missing information would materially change architecture or risk.

If the user has not provided a structure, suggest using assets/templates/project-intake-template.md.

Output Styles

Support three output weights:

• Lean Use for POC, uncertain ideas, or early exploration. Keep the blueprint short, single-agent by default, and focused on the minimum docs, contracts, and checks needed to avoid chaos.
• Standard Default. Use for MVPs and most new projects. Provide a complete three-layer blueprint with practical repo/docs structure, a clear execution loop, and meaningful verification.
• Production-Ready Use for projects preparing for launch, multi-person delivery, regulated domains, or higher reliability needs. Expand architecture rules, CI gates, evaluator rigor, rollout controls, and cleanup/anti-entropy mechanisms.

Selection rules:

• If the user specifies a style, honor it.
• If the user asks for "minimal", "lightweight", or "just enough", use Lean.
• If the user gives no style and the project is a normal MVP or internal tool, use Standard.
• If the user asks for production readiness, strong reliability, team scaling, compliance, or launch preparation, use Production-Ready.

Keep the same section order in every style. Change the depth, number of roles, and strictness of controls, not the overall shape.

Default Working Rules

• Start with a minimal harness, not a maximal one.
• Treat the repository as the long-term system of record.
• Keep specs, decisions, constraints, and acceptance criteria in files, not only in chat context.
• Separate implementation from evaluation when the task is long-running, subjective, or failure-prone.
• Define done before implementation begins.
• Prefer mechanical guards for architecture and quality whenever possible.
• Every added harness component must solve an observed or likely failure mode.

Three-Layer Output Contract

Unless the user asks for a different format, structure the blueprint in this order:

1. Assumptions
2. Foundation Layer
3. Execution Layer
4. Verification Layer
5. Artifacts to create now
6. What not to build yet
7. First implementation sequence

1. Assumptions

List only the assumptions that affect scope, architecture, or process. Keep them explicit and testable.

2. Foundation Layer

Define the static environment the agents will work in:

• repo layout
• docs layout
• architecture boundaries
• coding and naming rules
• lint, typecheck, test, and CI gates
• decision log and anti-entropy cleanup loop

Use assets/templates/architecture-boundaries-template.md and assets/templates/decision-log-template.md when the user wants concrete files.

3. Execution Layer

Define how work moves:

• whether to start with a single agent or multiple roles
• planner, generator, evaluator responsibilities if needed
• sprint size and contract flow
• handoff artifacts between roles
• context management strategy

Default progression:

• POC: single agent + small contracts + smoke validation
• MVP: single agent or planner/generator split + stronger verification
• Production: add explicit evaluator, cleanup loop, stricter gates, and broader observability

Use assets/templates/sprint-contract-template.md when the user wants a concrete contract format.

4. Verification Layer

Define how the system decides pass or fail:

• acceptance criteria
• quality rubric
• unit, integration, and end-to-end checks
• browser automation or API checks when relevant
• failure thresholds and retry loop
• which findings get written back into docs, rules, or tooling

Use assets/templates/quality-rubric-template.md when the user wants a starting rubric.

5. Artifacts To Create Now

Recommend only the files that are immediately useful. Typical first set:

• docs/specs/project-spec.md
• docs/architecture/boundaries.md
• docs/process/sprint-contract.md
• docs/quality/rubric.md
• docs/decisions/decision-log.md

If the user wants scaffolding, copy from the templates in assets/templates/.

6. What Not To Build Yet

Always call out over-engineering risks. Typical examples:

• too many agents before there is evidence they are needed
• heavy autonomy before basic validation exists
• large design systems before the first real workflows exist
• complex orchestration when single-agent + contract + verification is sufficient

7. First Implementation Sequence

Give a short, ordered rollout plan. Default order:

1. lock the project intake and acceptance criteria
2. create the foundation docs and repo conventions
3. define the first sprint contract template
4. implement one thin vertical slice
5. add verification around real failures
6. only then add more agent roles or automation

Style-Specific Defaults

Choose the lightest style that fits the project.

Lean

Use for POC or uncertain ideas:

• one agent
• project spec
• sprint contract
• lint and smoke tests
• manual or lightweight review
• minimal artifact list

Standard

Use for MVP:

• clear repo knowledge layer
• small contracts
• stronger CI gates
• explicit acceptance criteria
• evaluator or independent review for risky work
• practical first implementation sequence

Production-Ready

Use for launch preparation or long-running delivery:

• stable docs system of record
• architecture rules enforced in code
• dedicated evaluation loop
• end-to-end checks
• cleanup and refactoring cadence
• stronger rollout, reliability, and observability expectations

Template Assets

Use these bundled templates when the user asks for concrete artifacts:

• assets/templates/project-intake-template.md
• assets/templates/harness-blueprint-template.md
• assets/templates/sprint-contract-template.md
• assets/templates/quality-rubric-template.md
• assets/templates/architecture-boundaries-template.md
• assets/templates/decision-log-template.md

If the user asks for a reusable prompt or intake form, provide project-intake-template.md directly. If the user wants Codex to scaffold the initial workflow, use harness-blueprint-template.md as the output backbone.

When using the templates, carry the selected style into the output and make the scope match that style.