gad-eval-new-project

Inputs you should gather

Before writing anything, make sure you know:

1. Project name (kebab-case). Example: escape-the-dungeon, portfolio-bare.
2. Source design documents. Anything the user points at — game design docs, product requirements, spec markdown, XML from another tool. If the user hasn't named any, ask once; if still ambiguous, proceed with whatever is in the working directory and note the assumption.
3. Mode. greenfield (build from scratch) or brownfield (inherits a baseline codebase). Default to greenfield unless the user says otherwise.
4. Workflow. gad (full framework), bare (no framework), or emergent (inherits skills). Default to gad.
5. Buildable target. What the eval actually produces — a game, a site, a CLI. If there is no buildable target, stop and tell the user: methodology-only evals are rejected (gad-133).

If the user is vague, pick reasonable defaults and document them in a NOTES.md in the eval directory rather than blocking on a question.

The canonical directory layout

evals/<project-name>/
├── REQUIREMENTS.xml        # Single source of truth for what the agent must build
├── SCORING.md              # The rubric (four dimensions + composite weighting)
├── gad.json                # { "mode": "...", "workflow": "...", "buildable": true }
├── NOTES.md                # (optional) assumptions, source doc lineage
└── runs/                   # Populated later by gad eval run — do not create now

Do not create a runs/ directory during bootstrap. It is created by gad eval run and must stay empty until the first run, so gad eval verify can distinguish "bootstrapped but never run" from "run but not preserved."

REQUIREMENTS.xml shape

The requirements file is the contract the eval agent reads. Keep it machine-parseable and keep narrative out of the body — narrative belongs in the source design doc, which you can reference.

<Requirements project="escape-the-dungeon" version="1">
  <Intent>One-paragraph statement of what a successful build looks like.</Intent>
  <SourceDocs>
    <Doc path="design/GAMEPLAY-DESIGN.xml" role="primary" />
    <Doc path="design/STAT-AND-BEHAVIOUR-TAXONOMY.md" role="taxonomy" />
  </SourceDocs>
  <Deliverables>
    <Deliverable id="D1">Playable game build served from public/</Deliverable>
    <Deliverable id="D2">At least one boss encounter implementing the taxonomy</Deliverable>
  </Deliverables>
  <Constraints>
    <Constraint>All planning artifacts live under game/.planning/</Constraint>
    <Constraint>Source code under src/, assets under public/</Constraint>
  </Constraints>
  <Acceptance>
    <Check>`npm run build` exits 0</Check>
    <Check>TRACE.json present in run directory</Check>
  </Acceptance>
</Requirements>

Derive each <Deliverable> and <Check> from the source docs — do not invent. If the source doc is silent on acceptance, put one <Check> for a successful build and note the gap in NOTES.md.

SCORING.md shape

The four canonical dimensions come from task 14-04. Use them verbatim so cross-eval comparison stays meaningful — this is exactly the reason GAD chose a native harness over skill-creator's generic dimensions (decision gad-87).

# Scoring rubric — <project-name>

## Dimensions
1. CLI efficiency — tokens + tool calls per task completed.
2. Skill trigger accuracy — correct skills triggered at the right step.
3. Planning quality — task coverage, STATE.xml freshness, DECISIONS.xml hygiene.
4. Composite — weighted combination (default 0.25 each).

## Project-specific checks
- [Listed checks derived from REQUIREMENTS.xml Acceptance block]

Do not invent new dimensions. If the project genuinely needs something custom, add it as a project-specific check under dimension 4, not as a fifth dimension.

gad.json shape

{
  "mode": "greenfield",
  "workflow": "gad",
  "buildable": true,
  "buildCommand": "npm run build",
  "serveCommand": "npm run preview"
}

mode and workflow feed gad eval list. buildable: true is mandatory per gad-133. buildCommand must be real — if you don't know, use echo no-build and flag it in NOTES.md rather than hallucinating.

Step-by-step procedure

1. Create evals/<name>/ in the target repo.
2. Write gad.json first. This is how downstream tools even know the project exists.
3. Read the user's source docs end-to-end. Extract intent, deliverables, constraints, acceptance criteria.
4. Write REQUIREMENTS.xml referencing the source docs by path.
5. Write SCORING.md with the four canonical dimensions plus project-specific checks pulled from the Acceptance block of REQUIREMENTS.xml.
6. If you made any assumptions (default mode, missing acceptance criteria, invented build command), write NOTES.md recording them.
7. Verify by running gad eval list — the new project should appear. If it does not, the most common cause is a malformed gad.json.
8. Do NOT run the eval. Scaffolding and running are separate steps; running is the job of gad:eval-run.

What this skill does NOT do

• Running the eval — use gad:eval-run / gad:eval-bootstrap.
• Preserving outputs — use gad eval preserve (mandatory per gad-38, not optional).
• Grading or reporting — use gad eval report or gad:self-eval.
• Generating a TRACE.json — that is produced automatically by the trace hook during a run (gad-22, gad-58).

Stay in your lane. Handing a user a pre-populated runs/ directory or a hand-written TRACE.json will corrupt the eval pipeline's assumptions.

Common failure modes

• Inventing acceptance criteria. If the source doc is silent, say so in NOTES.md instead of making something up.
• Hallucinating a build command. Check package.json if present. If there is no buildable target at all, stop and tell the user the project fails gad-133.
• Creating runs/. Don't. It breaks gad eval verify.
• Adding a fifth scoring dimension. Put it as a project-specific check under composite instead, so cross-project comparison stays valid.
• Mixing up mode and workflow. Mode = start state (green/brown). Workflow = framework posture (gad/bare/emergent). They are independent axes.

When you're done

Report back with:

• The path to the new eval directory.
• Which source docs you ingested.
• Any assumptions you recorded in NOTES.md.
• The exact gad eval list line confirming registration.

Then stop. The next step belongs to gad:eval-run when the user is ready to actually execute.