# Project Scaffold > Set up agent-friendly project structures with AGENTS.md, specs, workflows, and TODO files for long-horizon autonomous execution. Use when starting a new project, onboarding to a brownfield codebase, or when a project lacks clear documentation for agents to follow. Do NOT use when the project already has a well-structured AGENTS.md, docs/, and specs/ directory. Do NOT use for single-file scripts, throwaway prototypes, or tasks that don't involve a codebase. - Skill: `agrimsingh/project-scaffold` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add agrimsingh/project-scaffold` - Raw SKILL.md: https://api.skillmd.com/api/skills/agrimsingh/project-scaffold/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: agrimsingh (https://skillmd.com/u/agrimsingh) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/agrimsingh/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.** | Artifact Type | Location | Purpose | | :--- | :--- | :--- | | Execution plans | `docs/plans/active/` and `docs/plans/completed/` | Track complex work in progress and retrospectives | | Specifications | `specs/` | Design intent for each system | | Quality tracking | `docs/quality.md` | Living scorecard of project health | | Build outputs | `dist/` or `build/` (gitignored) | Compiled artifacts | | Test reports | `coverage/` (gitignored) | Test coverage and property test results | | Generated reports | `docs/reports/` | Analysis, audits, or generated documentation | 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