Project Scaffold

Project Scaffold Skill

A skill for setting up agent-friendly project structures that enable long-horizon autonomous execution. Based on best practices from the OpenAI harness engineering approach and the loom repository pattern.

When to Use This Skill

Use this skill when:

• Starting a new project — Before writing any code, scaffold the documentation structure.
• Onboarding to a brownfield project — Create specs by reverse-engineering existing code.
• A project lacks clear documentation — Retrofit the structure to an existing codebase.
• Resuming a long-horizon task — The scaffold already exists; read AGENTS.md to orient, then follow TODO.md.

When NOT to Use This Skill

Do NOT use this skill when:

• The project already has a well-structured scaffold — If AGENTS.md, docs/, and specs/ already exist and are up to date, skip scaffolding and start executing.
• The task is a single-file script or throwaway prototype — This scaffold is for projects with multiple systems and long-horizon work. A one-off script doesn't need specs and workflows.
• You're asked to make a quick fix or answer a question — Don't scaffold a project just to fix a bug. Read the existing code, fix it, and move on.
• The user explicitly says they don't want this structure — Respect the user's preferences. Not every project needs this level of documentation.

Core Philosophy

AGENTS.md is a map, not an encyclopedia. Keep it to roughly 100 lines. It points to deeper sources of truth. The repository's knowledge base lives in structured directories — docs/ for architecture, beliefs, quality, and plans; specs/ for system specifications; .agents/workflows/ for task-specific instructions.

Rules enforce behavior, AGENTS.md provides context. .cursor/rules/ files are auto-injected into every agent turn — they enforce ongoing patterns like "update docs after changes" and "read the spec before coding." AGENTS.md is read for orientation; rules are the persistent behavioral guardrails.

Plans before code. For any complex work, create an execution plan (ExecPlan) before implementing. Plans are living documents that track progress, decisions, surprises, and outcomes.

Verification is built-in. Every spec tracks verification status. The multi-agent review loop and property-based testing are standard parts of the workflow, not afterthoughts.

What This Skill Creates

project-root/
├── AGENTS.md                          # ~100-line map pointing to everything below
├── .cursor/
│   └── rules/                         # Auto-injected behavioral rules for Cursor agents
│       ├── update-docs-after-changes.mdc  # Always: update docs/specs after implementation
│       ├── read-spec-before-coding.mdc    # On source edits: read spec first
│       └── artifacts-to-disk.mdc          # Always: write artifacts to project tree
├── docs/
│   ├── architecture.md                # Domain map, package layering, tech stack, conventions
│   ├── core-beliefs.md                # Agent-first operating principles
│   ├── quality.md                     # Per-domain quality scorecard (living grades)
│   └── plans/
│       ├── active/                    # Living execution plans for complex work
│       └── completed/                 # Finished plans (kept for retrospective)
├── specs/
│   ├── README.md                      # Index of all specs with verification status
│   ├── testing-strategy.md            # Testing approach: unit, property-based, UI property, review loop
│   └── {system-name}.md              # One spec per system/feature
├── TODO.md                            # Phased implementation checklist
└── .agents/
    └── workflows/
        ├── implement-and-verify.md    # Multi-agent review loop
        ├── safe-refactor.md           # Property-based testing for safe refactors
        ├── verify-ui-properties.md    # UI property testing with Bombadil (web projects only)
        └── {workflow-name}.md         # Other project-specific workflows

How to Use This Skill

Step 1: Gather Project Information

Before creating any files, ask the user these questions (or infer from context):

1. What is the project name and one-line description?
2. What are the major systems/features? (e.g., Auth, Database, API, UI, Integrations)
3. What's the tech stack? (Language, framework, database, deployment target)
4. Does this project have a web UI? (If yes, include the Bombadil UI property testing workflow and layer)
5. Is this greenfield or brownfield? If brownfield, what exists already?
6. What are the immediate priorities? (What should be built first?)

Step 2: Create the Scaffold

Create the directory structure and populate files using the templates below.

Order of creation:

1. .cursor/rules/ — Behavioral rules (always include, these enforce ongoing agent behavior)
2. docs/core-beliefs.md — Agent operating principles (use template as-is for most projects)
3. docs/architecture.md — Domain map, tech stack, conventions
4. docs/quality.md — Initial scorecard (all domains start at grade D or F)
5. specs/README.md — The spec index with verification status
6. specs/testing-strategy.md — Testing approach (always include this; includes Bombadil UI property testing section for web projects)
7. specs/{system}.md — One file per major system identified
8. AGENTS.md — The slim map pointing to everything above (references the rules)
9. TODO.md — The phased implementation checklist
10. .agents/workflows/implement-and-verify.md — Multi-agent review loop (always include)
11. .agents/workflows/safe-refactor.md — Property-based refactoring (always include)
12. .agents/workflows/verify-ui-properties.md — UI property testing with Bombadil (include if project has a web UI)
13. .agents/workflows/{name}.md — Other project-specific workflows
14. docs/plans/active/{plan}.md — ExecPlan for the first complex piece of work (if applicable)

Step 3: Validate with the User

After creating the scaffold, present a summary:

• List all specs created and their initial status
• Show the TODO.md phases
• Show the quality scorecard with initial grades
• Ask if any systems are missing

Step 4: Begin Execution

Once validated, the agent (or user) can begin executing against the specs:

1. Read AGENTS.md to orient (it's the map).
2. Read TODO.md to find the current phase and next task.
3. Read the spec file for the system you're touching (see specs/README.md). Include it in context.
4. For work touching 2+ systems or 5+ files: check docs/plans/active/ for an existing plan or create one.
5. Implement the feature following the spec.
6. Write tests (unit + property). See specs/testing-strategy.md.
7. (If web UI) Run UI property tests (.agents/workflows/verify-ui-properties.md).
8. Run the implement-and-verify workflow (.agents/workflows/implement-and-verify.md).
9. Fix any issues found by review subagents or Bombadil violations.
10. Before marking the phase complete, run the Done checklist: TODO.md, docs/quality.md, specs/README.md, and ExecPlan (if followed).
11. Repeat.

Templates

All templates are in the templates/ directory. Each uses {{PLACEHOLDER}} syntax for values that should be filled in per-project.

.cursor/rules/ Templates

Location: templates/rules/

Cursor rule files (.mdc) that are auto-injected into every agent context. These enforce ongoing behavioral patterns that AGENTS.md alone can't reliably enforce — because rules are injected automatically, agents can't skip or forget them.

Always generate these three rules:

• update-docs-after-changes.mdc (alwaysApply: true) — After any implementation, update TODO.md, quality.md, specs. This is the highest-impact rule: it closes the "agent forgets to document" gap.
• read-spec-before-coding.mdc (globs: src/, lib/, app/, packages/) — Before editing source code, read the relevant spec. Triggered only when source files are in context.
• artifacts-to-disk.mdc (alwaysApply: true) — Write plans, specs, reports to the project tree, not just conversation.

Customizing rules: Copy from templates/rules/ and edit. The glob patterns in read-spec-before-coding.mdc should match the project's source directory structure. Add project-specific rules as needed (e.g., a rule for database migration conventions).

Why rules instead of more AGENTS.md content: AGENTS.md is read once to orient. .cursor/rules/ files are injected into every agent turn. For behaviors that must happen every time (like updating docs), rules are the enforcement mechanism. AGENTS.md is the map; rules are the laws.

AGENTS.md Template

Location: templates/AGENTS.template.md

This is the slim ~100-line map. It contains:

• Non-Negotiable Rules (top of file) — The 4 key rules that apply to every task. Front-loaded so agents see them first.
• Repository map table pointing to all docs, specs, plans, workflows, and cursor rules
• Commands table (install, dev, test, build, deploy)
• Brief code style summary (detail lives in docs/architecture.md)
• "How to Work in This Repo" section with documentation updates embedded as step 7 of the implementation flow (not a separate checklist)
• Environment variables table

Key principle: Non-negotiable rules go at the top. Everything else is a map. If you're tempted to add detail, put it in docs/architecture.md or a spec instead, and add a pointer here.

docs/architecture.md Template

Location: templates/docs/architecture.template.md

The detailed architecture document. This is where the detail that used to live in AGENTS.md goes:

• System overview and high-level architecture diagram
• Domain map (each domain linked to its spec and code location)
• Full directory structure
• Package layering and dependency rules
• Key files table
• Tech stack table
• Naming conventions and formatting rules
• Database, error handling, logging, security, and debugging sections

docs/core-beliefs.md Template

Location: templates/docs/core-beliefs.template.md

Agent-first operating principles organized into six categories:

• On Specifications — Specs are source of truth, living documents, must be verifiable
• On Planning — Plans before code, self-contained, living documents
• On Quality — Verification over trust, observable outcomes, fix the system not the symptom
• On Context — Context is scarce, repository is the memory, stale docs are dangerous
• On Implementation — Depth-first, small verifiable steps, idempotent and safe
• On Simplicity — Design for removal, selective documentation, start simple

For most projects, use this template as-is. Customize only if the project has unusual constraints.

docs/quality.md Template

Location: templates/docs/quality.template.md

A living scorecard that grades each domain and architectural layer:

• Grades: A (production-ready) through F (not started)
• Dimensions: Spec, Code, Tests, Review, Overall
• Architectural layers: Error handling, Security, Observability, Performance, CI, Documentation
• Known Gaps: Specific issues with severity and links to plans
• Score History: Track how grades change over time

Update this after every phase completion.

docs/plans/exec-plan.md Template

Location: templates/docs/plans/exec-plan.template.md

For complex, multi-step work. Based on OpenAI's ExecPlan format. Required sections:

• Purpose / Big Picture — What someone gains after this change
• Current State — Describe as if reader knows nothing
• Plan of Work — Prose describing the sequence of edits
• Milestones — Each independently verifiable
• Concrete Steps — Exact commands, expected output
• Validation and Acceptance — Behavior-based acceptance criteria
• Idempotence and Recovery — Safe retry/rollback paths
• Interfaces and Dependencies — Types, signatures, libraries

Living sections (must be kept up to date):

• Progress — Checkboxes with timestamps
• Surprises & Discoveries — Unexpected findings with evidence
• Decision Log — Every significant decision with rationale
• Outcomes & Retrospective — Lessons learned at milestones
• Revision Notes — What changed in the plan and why

Key principle: An ExecPlan must be fully self-contained. A complete novice should be able to implement from just the plan.

specs/README.md Template

Location: templates/specs/README.template.md

The spec index. Enhanced with verification tracking:

• Status column: Draft, In Progress, Implemented, Needs Update, Planned
• Verified column: Yes (with date), Partial, No, Stale
• Instructions for creating, updating, and verifying specs

specs/{system}.md Template

Location: templates/specs/system.template.md

One spec per system/feature. Sections:

• Overview, Architecture, Core Types, API/Interface
• Request/Response examples, Error Handling, Security
• Design Decisions (with rationale), Dependencies, Future Considerations

specs/testing-strategy.md Template

Location: templates/specs/testing-strategy.template.md

The testing approach for the project:

• Four-layer testing pyramid: unit → property-based (fast-check) → UI property (Bombadil) → multi-agent review
• Property-based testing with fast-check (arbitraries, invariants, equivalence)
• UI property testing with Bombadil (temporal logic formulas, autonomous exploration, violation detection) — for web projects
• Multi-agent review loop integration
• When to use each type of test

TODO.md Template

Location: templates/TODO.template.md

Phased implementation checklist with verification steps built into each phase.

Workflow Templates

Location: templates/workflows/

• implement-and-verify.md — Multi-agent review loop (implement → self-review → spawn 2 subagents → fix → re-review, max 3 rounds)
• safe-refactor.md — Property-based testing for safe refactors (bridge old/new → fast-check equivalence → Bombadil UI check → replace)
• verify-ui-properties.md — UI property testing with Bombadil (spec → temporal logic properties → autonomous exploration → violation reporting). Include for web projects only.
• workflow.template.md — Generic workflow template for project-specific workflows

Example: Task Manager App

See examples/task-manager/ for a fully worked example of this scaffold applied to a task manager application with auth and Slack integration. The example demonstrates:

• .cursor/rules/ with filled-in behavioral rules (auto-injected enforcement)
• A slim AGENTS.md with Non-Negotiable Rules at the top and doc updates embedded in the implementation flow
• Filled-out architecture, core-beliefs, and quality docs
• Specs with verification status
• A sample ExecPlan for the Slack integration feature
• A phased TODO.md with verification steps
• Workflows for review, UI property testing, and deployment

Artifact Handoff Convention

Establish a clear boundary for where generated artifacts live. The mental model: tools write to disk, models reason over disk, developers retrieve from disk.

When the agent generates an artifact (a report, a plan, a spec), it should always write it to the appropriate location in the project tree — never leave important output only in the conversation.

Tips for Effective Use

1. Keep AGENTS.md slim. If it grows past 100 lines, you're putting too much in it. Move detail to docs/ or specs/.
2. Be specific about types. Don't say "user data" — define the exact fields in the spec.
3. Include examples. Show request/response payloads, not just descriptions.
4. Explain the "why." Design decisions are as important as the design itself.
5. Update docs as you go. A stale doc is worse than no doc.
6. Use ExecPlans for complex work. If it touches more than one system or takes more than an hour, it needs a plan.
7. Grade honestly. The quality scorecard only works if grades reflect reality.
8. Design for removal. As models improve, the scaffolding should get simpler.
9. Write artifacts to disk, not just to chat. Every important output should live in the project tree.

Checklist for Scaffold Creation

When using this skill, ensure you:

• Created .cursor/rules/update-docs-after-changes.mdc (always-on doc update enforcement)
• Created .cursor/rules/read-spec-before-coding.mdc (spec-first development)
• Created .cursor/rules/artifacts-to-disk.mdc (write artifacts to project tree)
• Created docs/core-beliefs.md (agent operating principles)
• Created docs/architecture.md (domain map, tech stack, conventions)
• Created docs/quality.md (initial scorecard with honest grades)
• Created docs/plans/active/ and docs/plans/completed/ directories
• Created specs/README.md with index and verification status
• Created specs/testing-strategy.md with testing approach
• Created one specs/{system}.md per major system
• Created AGENTS.md as a slim map (~100 lines) with Non-Negotiable Rules at top
• Created TODO.md with phased implementation plan
• Created .agents/workflows/implement-and-verify.md (multi-agent review loop)
• Created .agents/workflows/safe-refactor.md (property-based refactoring)
• Created .agents/workflows/verify-ui-properties.md (UI property testing — web projects only)
• Validated the scaffold with the user before proceeding