architecture-bootstrap

name: architecture-bootstrap description: Bootstrap project architecture governance. Use when the user says "bootstrap architecture", "create ARCHITECTURE.md", "set up codebase structure", or "add architecture governance to project".

Architecture Bootstrap

Use this skill to make architecture placement explicit before implementation agents write files. The goal is a project-specific ARCHITECTURE.md, a reusable per-task PLACEMENT_PLAN.md template, and an optional generator scaffold that makes the correct location the easiest location.

Workflow

1. Audit the existing structure

   • Inspect the project root and src/ tree before proposing rules.
   • Identify existing layers such as primitives, feature modules, layouts, contexts/providers, shared utilities, tests, and app shells.
   • Note ambiguous or overloaded folders instead of silently normalizing them.

2. Interview the user with focused Q&A Ask only the questions needed to make placement rules concrete:

   • Which layer names should this project use (for example shared/ui, features/<feature>, layouts, contexts)?
   • What belongs in each layer, and what must never go there?
   • What naming conventions should components, hooks, services, tests, and routes follow?
   • Which imports should be forbidden across layers?
   • Which paths should generators/scaffolds create by default?

3. Generate ARCHITECTURE.md from the template

   • Start from references/architecture-template.md.
   • Replace placeholders with project-specific decisions from the audit and Q&A.
   • Keep the file concise enough for implementer agents to read before editing.
   • Reference ecosystem precedent when explaining why the artifact exists: Cursor Project Rules, Cline Rules + Memory Bank, Devin AGENTS.md, and Aider conventions all use persistent project rules to keep agents aligned.

4. Generate a per-task placement plan

   • Use references/placement-plan-template.md whenever a project already has ARCHITECTURE.md and the upcoming task creates, moves, or reorganizes files.
   • The implementer fills PLACEMENT_PLAN.md before Edit/Write tool use.
   • The reviewer compares the final diff against the plan and treats unexplained placement drift as a retry condition.

5. Optionally install a component generator scaffold

   • Copy references/gen-component-template.mjs into the project only when the user wants scaffolding.
   • Customize it to the project-specific ARCHITECTURE.md; do not pretend one global generator fits every repository.

Output

For a bootstrap request, produce:

• ARCHITECTURE.md draft or patch plan.
• PLACEMENT_PLAN.md template or first task-specific plan.
• Optional customized gen-component.mjs scaffold.
• A short adoption note explaining how implementer and reviewer agents should use the artifacts.