# Project Scaffold Skill

A project-specific autonomous development harness builder.
Canonical purpose: see [INTENT.md](INTENT.md).
Detailed feedback-layer model: see [docs/feedback-layer-model.md](docs/feedback-layer-model.md).

This skill bootstraps any project (greenfield or existing) with an
**adaptive harness** for continuous, autonomous, high-quality development.

Not just a one-time scaffold — the agent discovers what the project needs,
confirms with the human, generates only the confirmed artifacts, then operates
indefinitely: **iterate → verify → record → audit/promote → evolve harness**.

## What It Does

### Phase 0-4: Bootstrap (one-time)

1. **Discovers** the codebase autonomously (tech stack, architecture, tests, CI, quality infra)
2. **Assesses** what harness artifacts (docs, scripts, operational prompts) the project needs
3. **Asks the human** only for decisions that cannot be inferred + confirms the harness shape
4. **Generates** only the confirmed artifacts from templates (adapted, not rigid)
5. **Writes two machine-readable contracts**:
   - `docs/harness-manifest.json` for artifact inventory + execution contract
   - `docs/feedback-profile.json` for feedback surfaces + gaps + business-flow coverage
6. **Mechanically validates** everything before handoff (no TBD, no broken cross-refs)

### Phase 5: Continuous Operation (runs forever)

7. Agent **iterates** using the `$iterate` sub-skill (implement → verify → record)
8. Agent **audits quality** periodically using `$quality-audit` (if installed)
9. Agent **promotes milestones** using `$milestone-promote` (if installed, and it also captures review packets plus doc sync)
10. Agent **evolves the harness** — improving docs, scripts, and constraints through use
11. If quality score drops below threshold, **debt cleanup is mandatory** before new features

## Generated Artifacts (adaptive)

Which artifacts are generated depends on the **Harness Needs Assessment** (Phase 0k)
and the human's confirmation (Phase 1d). Not every project gets every artifact.
The exact generated set is recorded in `docs/harness-manifest.json`, while the
feedback-layer state is recorded in `docs/feedback-profile.json`.

### Documents (generated based on project needs)

| Role | Default file | Always? |
|---|---|---|
| `agents_doc` | `AGENTS.md` | Yes |
| `prompt_doc` | `docs/prompt.md` | Yes |
| `plan_doc` | `docs/plan.md` | Yes |
| `implement_doc` | `docs/implement.md` | Yes |
| `project_spec_doc` | `docs/project_spec.md` | Recommended |
| `documentation_doc` | `docs/documentation.md` | Recommended |
| `failure_taxonomy_doc` | `docs/failures/taxonomy.md` | Recommended |
| `compaction_doc` | `docs/compaction-strategy.md` | When long sessions expected |
| `harness_manifest` | `docs/harness-manifest.json` | Yes |
| `feedback_profile` | `docs/feedback-profile.json` | Yes |

### Scripts (platform-adaptive)

| File | Generated when |
|---|---|
| `scripts/quality-gates.sh` / `.ps1` | Quality tools exist; variant matches team's OS |
| `scripts/validate-docs.sh` / `.ps1` | Multiple docs generated; variant matches team's OS |

Cross-platform variants (.sh + .ps1) are only generated when the team uses multiple OS.

### Operational sub-skills (installed based on need)

| Skill | Purpose | Always? |
|---|---|---|
| `$iterate` | Single iteration cycle (implement → verify → record → decide) | Yes |
| `$quality-audit` | Full quality audit + tech debt scan + quality score | If quality tools exist |
| `$milestone-promote` | Safe milestone transition with full verification | If multiple milestones |

## Installation

```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/
```

## Usage

Tell your AI agent (Codex, Claude Code, Windsurf, etc.):

> Run the $project-scaffold skill to set up this repo for autonomous development.

The agent will:
1. Explore your codebase automatically and assess harness needs (Phase 0)
2. Ask you key questions and confirm what artifacts to generate (Phase 1)
3. Propose milestones — M0 ensures verification capability (Phase 2)
4. Generate only the confirmed artifacts (Phase 3)
5. Run mechanical validation, then hand off (Phase 4)
6. Enter continuous operation loop, evolving the harness over time (Phase 5)

## Directory Structure

```
project-scaffold-skill/
├── README.md                          # This file
├── SKILL.md                           # Navigation layer — design principles + phase index
├── phases/                            # Detailed phase instructions (progressive disclosure)
│   ├── phase-0-discovery.md           # Autonomous exploration + harness needs assessment
│   ├── phase-1-alignment.md           # Human decisions + harness shape confirmation
│   ├── phase-2-milestones.md          # Adaptive milestone decomposition
│   ├── phase-3-generation.md          # Generate only confirmed artifacts
│   ├── phase-4-validation.md          # Mechanical self-check + handoff
│   ├── phase-5-operation.md           # Continuous loop + harness evolution
│   └── anti-patterns.md               # What NOT to do
├── templates/                         # Document & script templates (starting points)
│   ├── AGENTS.md.tmpl
│   ├── project_spec.md.tmpl
│   ├── prompt.md.tmpl
│   ├── plan.md.tmpl
│   ├── implement.md.tmpl
│   ├── documentation.md.tmpl
│   ├── taxonomy.md.tmpl
│   ├── compaction-strategy.md.tmpl
│   ├── harness-manifest.json.tmpl
│   ├── feedback-profile.json.tmpl
│   ├── validate-docs.sh.tmpl
│   ├── validate-docs.ps1.tmpl
│   ├── quality-gates.sh.tmpl
│   └── quality-gates.ps1.tmpl
├── tools/                             # Helper utilities
│   └── render-scaffold.mjs            # Placeholder renderer for docs/scripts
├── sub-skills/                        # Small reusable operational prompt set
│   ├── iterate/SKILL.md
│   ├── quality-audit/SKILL.md
│   └── milestone-promote/SKILL.md
└── evals/                             # Eval suite for testing the skill itself
    ├── prompts.csv                    # 23 test prompts (explicit/implicit/adaptive/negative)
    ├── grader.mjs                     # Deterministic protocol-compliance grader
    ├── fixture-runner.mjs             # Prepare/verify fixture repos for scaffold self-tests
    ├── capture-failure-case.mjs       # Turn a reported failure into a new eval case
    ├── SELF-TEST-MODE.md              # Self-test mode instructions for fixture runs
    ├── fixtures/                      # Minimal repos used to probe scaffold behavior
    └── rubric.schema.json             # Rubric schema for qualitative scoring
```

## Design Principles

- **Repo is the single source of truth** — anything not in the repo doesn't exist for the agent
- **AGENTS.md is a table of contents, not an encyclopedia** — max 150 lines
- **Rules in code, not just prose** — linters, scripts, CI checks > documentation promises
- **Progressive disclosure** — agent navigates from map to detail, never overwhelmed
- **Prefer boring technology** — composable, stable, well-represented in training data
- **Prompt first, discovery second, enforcement last** — never encode project-specific answers; only encode universal safety and verification contracts
- **Configuration emerges from discovery and dialogue** — do not hardcode; derive from Phase 0 discovery and Phase 1 human alignment
- **Harness is a living system** — documents, scripts, constraints, and a small operational prompt set evolve through use
- **Uncertainty protocol** — discover first, ask if uncertain, record every human interaction to improve the harness
- **Platform-native execution contract** — Windows defaults to `.ps1`, Unix-like environments default to `.sh`, and docs plus the manifest must use one consistent primary command pair
- **Two machine-readable contracts**:
  `docs/harness-manifest.json` declares which artifacts were intentionally generated and
  `docs/feedback-profile.json` declares which feedback surfaces exist plus where they are weak
- **Mechanical enforcement over trust** — validate-docs and quality-gates run every commit through the repo's primary command pair
- **Continuous operation** — Phase 0-4 is setup; Phase 5 runs forever
- **Escalating recovery** — L1 retry → L2 adjust → L3 rollback+replan → L4 escalate to human
- **Safe rollback only** — revert only files from the active iteration; never use repository-wide rollback commands

## Running Evals

To test whether the skill produces correct output:

```bash
# 1. Run the skill on a test repo
codex exec --full-auto 'Use the $project-scaffold skill to set up this repo.'

# 2. Grade the output deterministically
node evals/grader.mjs <project-dir>

# 3. (Optional) Run qualitative rubric grading
codex exec \
  "Evaluate the scaffold output against the rubric." \
  --output-schema evals/rubric.schema.json
```

These evals validate the scaffold itself, not the target project's business behavior.
Use fixture repos that cover:
- UI/API/CLI projects where E2E should be proposed
- Pure libraries where browser/API E2E should not be invented
- Empty repos where E2E may be deferred until a real user-facing surface exists
- Existing repos with stale AGENTS/docs that must be audited, archived, and reorganized

Fixture workspaces are initialized as local git repositories so discovery commands
like `git rev-parse` and `git log -1` behave like a normal project checkout.

Fixture workflow:

```bash
# 1. Prepare a workspace from a fixture repo
node evals/fixture-runner.mjs prepare node-cli tmp/node-cli --force

# 2. Run Codex inside that workspace
cd tmp/node-cli
codex exec --full-auto "Use the $project-scaffold skill to set up this repo for autonomous development."

# 3. Verify the scaffolded output against the fixture expectations
node ../../fixture-runner.mjs verify node-cli .
```

`verify` now runs the generated primary doc validation and primary quality gate
commands in addition to the structural grader, so a scaffold only passes when
its own mechanical checks succeed. For reorganize fixtures it also checks that
stale docs were archived and removed from the canonical doc set.

One-shot workflow with timeout handling:

```bash
node evals/fixture-runner.mjs run empty-repo tmp/empty-repo --force --timeout-ms 600000
```

Repeat-run workflow for stability/distribution checks:

```bash
node evals/fixture-runner.mjs repeat empty-repo tmp/empty-repo-dist --runs 3 --timeout-ms 600000
```

This writes a distribution artifact at `tmp/empty-repo-dist-summary.json`.

Compare two saved eval results to detect regressions:

```bash
node evals/fixture-runner.mjs compare evals/history/baseline.json evals/history/current.json
```

The compare command exits non-zero when a previously passing check regresses.
Use `evals/history/` to keep dated snapshots of important runs.

Retirement/ablation workflow:

```bash
node evals/fixture-runner.mjs ablate empty-repo tmp/empty-repo-ablate --force --timeout-ms 600000
```

This writes an ablation artifact inside the workspace so the retirement check is
captured in the repo, not only in terminal output.

Capture a reported failure as a new eval case:

```bash
node evals/capture-failure-case.mjs --id failure-001 --prompt "Use the $project-scaffold skill to ..." --should-trigger true --category captured-failure --notes "Reported by a real user run"
```

The runner injects fixture-specific Phase 1 alignment answers and tells Codex to
stop after Phase 4, so the self-test exercises scaffold setup rather than the
infinite Phase 5 loop.

If `codex exec --json` produces a `.codex-trace.jsonl` file, keep it as a debug
artifact only. It is not part of the pass/fail grading contract.

## Test Layers

Use three layers of confidence:

1. Static checks
   Validator syntax, grader syntax, and placeholder detection.
2. Fixture self-tests
   Run the skill on representative repos and verify scaffold behavior boundaries
   such as execution-contract consistency and whether E2E gates are invented or omitted correctly.
3. Human-in-the-loop acceptance
   For real projects, confirm that the generated North Star, milestones, and constraints
   still match the user's intent before letting the repo enter long-running autonomous work.
