---
name: project-scaffold
description: >
  Project-specific autonomous development harness builder. Bootstraps any
  project (greenfield or existing) with an adaptive harness for continuous,
  autonomous, high-quality development. Discovers what the project needs,
  confirms with the human, generates only the confirmed artifacts, then
  operates continuously while strengthening the project's feedback loops,
  constraints, and recovery paths. Drop this skill into any repo's
  .agents/skills/ to activate.
---

# Project Scaffold — Full-Loop AI Development Operating System

## Overview

Canonical purpose: see [INTENT.md](INTENT.md).

This skill turns any codebase into a **project-specific autonomous development
harness** for a continuously operating AI agent. It is not just a one-time
scaffold. It is an ongoing development loop with mechanical quality
enforcement, explicit constraints, and feedback paths that help the agent tell
when it changed the wrong thing.

**What it does:**

1. **Discovers** the project's structure, tech stack, quality tools, and existing docs
2. **Assesses** what harness artifacts (docs, scripts, sub-skills) the project needs
3. **Confirms** the harness shape with the human — nothing is generated without agreement
4. **Generates** only the confirmed artifacts from templates (adapted, not rigid)
5. **Operates** continuously: iterate > verify > record > audit/promote
6. **Evolves** the harness itself through use — docs, scripts, constraints, and a small operational prompt set improve over time

### Two modes

| Scenario | What happens |
|---|---|
| **Greenfield** (no docs exist) | Discover > assess > confirm > generate from templates |
| **Messy-existing** (docs exist but disorganized) | Audit > diagnose > confirm > reorganize > fill gaps |

### Design principles

1. **Repo is the single source of truth** — anything not in the repo doesn't exist for the agent
2. **AGENTS.md is a table of contents, not an encyclopedia** — max 150 lines, points to deeper docs
3. **Rules in code, not just prose** — every constraint that can be automated, is automated
4. **Progressive disclosure** — agent reads this file first, then navigates to phase details as needed
5. **Prefer boring technology** — composable, stable, well-represented in training data
6. **Mechanical enforcement over trust** — linters, scripts, CI checks > documentation promises
7. **Continuous operation** — scaffold is Phase 0-4; daily work is Phase 5 (runs forever)
8. **Safe rollback only** — revert only files from the active iteration; never use repository-wide rollback commands
9. **Prompt first, discovery second, enforcement last** — never encode project-specific answers; only encode universal safety and verification contracts
10. **Harness is a living system** — documents, scripts, constraints, and the operational prompt set evolve through use, not just during scaffold setup
11. **Configuration emerges from discovery and dialogue** — do not hardcode project-specific answers into templates; derive them from Phase 0 discovery and Phase 1 human alignment

### Uncertainty protocol (applies to ALL phases and sub-skills)

When the agent encounters something it is not sure about:

1. **Try to discover the answer** from the repo first (read code, read docs, run commands)
2. If a candidate answer is found, **tag it as `inferred`** and continue,
   but confirm with the human at the next natural interaction point
3. If no answer can be inferred, **ask the human immediately**, do not guess
4. If the cost of guessing wrong is high (affects architecture, security, hard
   constraints, or would require significant rework), **ask the human even if
   you have a candidate answer**
5. **Record every "ask the human" event** — what was asked, why, and the answer.
   Use this to improve the harness so the same question doesn't arise again
   (add a doc, add a constraint, add context to AGENTS.md)

This protocol applies uniformly to scaffold generation (Phase 0-4) and continuous
operation (Phase 5).

---

## Phase Navigation

Each phase has detailed instructions in a separate file under `phases/`.
Read only the phase you are currently executing — do not pre-load all phases.

| Phase | Purpose | Details |
|---|---|---|
| **Phase 0: Discovery** | Explore the project autonomously, assess harness needs | `phases/phase-0-discovery.md` |
| **Phase 1: Alignment** | Ask the human for decisions, confirm harness shape | `phases/phase-1-alignment.md` |
| **Phase 2: Milestones** | Decompose the path to North Star into milestones | `phases/phase-2-milestones.md` |
| **Phase 3: Generation** | Generate only the confirmed artifacts | `phases/phase-3-generation.md` |
| **Phase 4: Validation** | Mechanical self-check, then present to user | `phases/phase-4-validation.md` |
| **Phase 5: Operation** | Continuous loop: iterate, audit, promote, evolve harness | `phases/phase-5-operation.md` |

**Anti-patterns**: `phases/anti-patterns.md`

**Self-test mode** (fixture runs): `evals/SELF-TEST-MODE.md`

### Phase flow

```
Phase 0 (autonomous) --> Phase 1 (human) --> Phase 2 (milestones)
    --> Phase 3 (generate) --> Phase 4 (validate) --> Phase 5 (forever)
```

The agent pauses for human input only at:
- **Phase 1**: core decisions, inference confirmation, harness shape
- **Phase 4**: final review before entering continuous operation
- **During Phase 5**: only when the Uncertainty Protocol or L4 escalation triggers

---

## Key Concepts (quick reference)

### Harness Needs Assessment (Phase 0k)

Instead of always generating a fixed bundle of docs, scripts, and operational prompts,
the agent assesses what the project actually needs based on discovery.
Document roles, scripts, and operational prompts are each marked as
`needed` / `recommended` / `not-needed-yet`. The human confirms in Phase 1d.
The confirmed result is then encoded in two machine-readable contracts:
`docs/harness-manifest.json` for artifact inventory + execution contract, and
`docs/feedback-profile.json` for feedback surfaces + gaps + business-flow coverage.

### Adaptive Quality Dimensions (Phase 1d + quality-audit)

Quality scoring dimensions are NOT a fixed 5x20 grid. They are discovered in
Phase 0, confirmed with the human in Phase 1d, and recorded in project docs.
Dimensions can be added, removed, or re-weighted during operation.

### Harness Evolution (Phase 5)

The harness is not frozen after Phase 4. During continuous operation:
- After every L2/L3 recovery: ask what was missing from the environment
- After every milestone: review whether the harness needs an upgrade
- After every quality-audit: check harness health
- Record all harness improvements in the Decision Log

### M0 Adaptive (Phase 2)

M0 is not always "Quality Infrastructure." Its content depends on what Phase 0
discovered. The invariant is: **before any feature work, at least one quality
gate command must be runnable.**

---

## Templates and Sub-skills

Templates in `templates/` are **reference starting points**, not rigid structures.
Adapt, extend, or omit sections based on what was discovered and confirmed.

### Available templates

| Role | Template |
|---|---|
| `agents_doc` | `templates/AGENTS.md.tmpl` |
| `project_spec_doc` | `templates/project_spec.md.tmpl` |
| `prompt_doc` | `templates/prompt.md.tmpl` |
| `plan_doc` | `templates/plan.md.tmpl` |
| `implement_doc` | `templates/implement.md.tmpl` |
| `documentation_doc` | `templates/documentation.md.tmpl` |
| `failure_taxonomy_doc` | `templates/taxonomy.md.tmpl` |
| `compaction_doc` | `templates/compaction-strategy.md.tmpl` |
| `harness_manifest` | `templates/harness-manifest.json.tmpl` |
| `feedback_profile` | `templates/feedback-profile.json.tmpl` |

### Available operational sub-skills

| Skill | Purpose |
|---|---|
| `iterate` | Execute one iteration cycle within current milestone |
| `quality-audit` | Full quality audit + tech debt scan + quality score |
| `milestone-promote` | Safely promote from one milestone to the next |

### Tools

| Tool | Purpose |
|---|---|
| `tools/render-scaffold.mjs` | Mechanically render templates from a values JSON file |

---

## Usage

To activate this skill in a new project:

```text
PowerShell:
  Copy-Item -Recurse -Force project-scaffold-skill "<your-project>/.agents/skills/project-scaffold"

Unix:
  cp -R project-scaffold-skill/ <your-project>/.agents/skills/project-scaffold/

Then tell Codex/Claude:
  Run the $project-scaffold skill to set up this repo for autonomous development.
```

The AI agent will execute Phase 0-4 automatically, only pausing for Phase 1
(human decisions) and Phase 4 (final review). After handoff, the agent
enters Phase 5 and operates continuously using the installed operational sub-skills.
