Project scaffolding

info

This page explains what init_project creates, why the structure exists, and how AI agents use it.

MCP Task Server series

1. MCP Task Server
2. Architecture
3. Tools
4. Multi-agent coordination
5. Project scaffolding - You are here

The problem

AI agents lose context between sessions. Every new conversation starts from scratch with no memory of previous decisions, no understanding of the project structure, and no consistent rules to follow.

Without structure, agents:

• Make inconsistent architectural decisions
• Forget previous implementation choices
• Repeat the same questions about conventions
• Have no record of what was tried and why it failed
• Cannot hand off work to other agents effectively

I needed a way to give agents persistent context that survives across sessions and provides a consistent framework for how they should work.

The solution

init_project generates 28 template files across three directories that give AI agents everything they need to work effectively on your project:

Directory	Purpose
agent-kit/	Role definitions, permissions, and handoff protocols
memory_bank/	Project context, architecture docs, execution tracking, and task storage
.cursor/rules/	Cursor-specific rules that tell agents to read the memory_bank first

Usage

# Initialise with auto-detected project name
call init_project

# Initialise with custom name
call init_project({ project_name: "my-app" })

# Force overwrite existing files
call init_project({ force: true })

# Sync rules to existing project (add missing only)
call sync_rules

# Preview what would change
call sync_rules({ dry_run: true })

# Update existing rules to latest templates
call sync_rules({ update_existing: true })

What gets created

agent-kit/

Role definitions and coordination protocols for multi-agent workflows.

File	Purpose
AGENT_RULES.md	Defines Planner, Worker, and Judge roles with permissions
KICKOFF.md	Session startup checklist
TASKS.md	Points agents to task storage in memory_bank
HANDOFF.md	Protocol for transferring work between agents
SHARED_CONTEXT.md	Documents the shared context system

Why it matters: Agents need explicit rules about what they can and cannot do. Without role definitions, a Worker agent might start creating tasks (Planner's job) or approving its own work (Judge's job). The agent-kit provides guardrails.

memory_bank/

Persistent project context organised into four areas.

memory_bank/architecture/

Technical documentation that agents reference when making implementation decisions.

File	Purpose
architecture.md	High-level system architecture
tech.md	Technology stack and versions
models.md	Data models and schemas
services.md	System services and integrations
deployment.md	Deployment configuration
kubernetes.md	Kubernetes manifests (if applicable)
webhooks.md	Webhook implementations (if applicable)

Why it matters: Agents make better decisions when they understand the existing architecture. Without this, they might suggest incompatible technologies or duplicate existing functionality.

memory_bank/context/

Project-level context that helps agents understand the bigger picture.

File	Purpose
context.md	Index to context files
brief.md	Project overview, goals, and constraints
active.md	Current focus and priorities
product.md	Product context and requirements
canvas.md	Lean canvas for business context
changelog.md	Record of significant changes

Why it matters: Agents that understand the project brief make suggestions aligned with project goals rather than generic best practices that might not fit.

memory_bank/execution/

Tracking for decisions, progress, and debugging.

File	Purpose
execution.md	Execution overview
progress.md	Task summary (auto-synced from tasks.json)
decisions.md	Decision log with rationale
debug.md	Debug diary for tracking issues
git.md	Git conventions and code quality rules

Why it matters: The decision log prevents agents from revisiting decisions that were already made. The debug diary helps agents learn from previous troubleshooting. Progress tracking shows what is done versus what remains.

memory_bank/tasks/

Task storage managed by the MCP server.

File	Purpose
tasks.json	Machine-readable task registry (source of truth)
task_001.txt	Human-readable detailed task file
task_002.txt	...

Why it matters: Tasks with dependencies, priorities, and subtasks give agents clear direction. The dual storage (JSON for machines, text for humans) means both agents and humans can work with the same data.

memory_bank/reference/

Space for reference materials specific to your project.

File	Purpose
README.md	Index for reference materials

Why it matters: Large codebases need documentation for complex subsystems. This is where you put API docs, integration guides, or anything agents need to reference repeatedly.

.cursor/rules/

Cursor-specific configuration.

File	Purpose
agent-workflow.mdc	Task management protocol - tells agents to read memory_bank before acting
wellness-check.mdc	Break reminders based on session time and duration
shared-context-sync.mdc	Memory sync guidance for preferences

Why it matters: Without these rules, Cursor agents start working without reading the project context or checking your preferences. The rules ensure agents:

• Check the memory_bank first for full project context
• Respect your wellness preferences with break reminders
• Apply your shared memory preferences to content they create

The workflow

After scaffolding

Once init_project has run:

1. Fill in the context files - Start with brief.md (project overview) and tech.md (technology stack). These are the most frequently referenced.

2. Add architecture details - As you make decisions, document them in the architecture files. Future agents will thank you.

3. Use the decision log - When you make a significant choice, add it to decisions.md with the rationale. This prevents revisiting the same decisions.

4. Let progress auto-sync - The progress.md file updates automatically when tasks change. You do not need to maintain it manually.

Customisation

The templates are starting points. Modify them to fit your project:

• Remove files you do not need (e.g., kubernetes.md for non-Kubernetes projects)
• Add files for your specific needs (e.g., api.md for API documentation)
• Update the cursor rules to match your workflow

info

The MCP server does not depend on specific file names. It only uses tasks.json and progress.md directly.