fbenitezrtw/project-bootstrap-architect

Project Bootstrap Architect

Description

Meta-skill that automatically configures the entire professional development ecosystem for any project: specialized AI sub-agents, operational/strategic/memory playbooks, IDE rules, recommended skills, and MCP server configurations. Equivalent to having a Staff Engineer bootstrap the development infrastructure on day one.

When to Activate

• User says "bootstrap my project", "configure development environment", "project setup", "set up agents"
• User has a new project and wants professional structure
• User mentions "project-bootstrap-architect" directly
• User asks "create sub-agents for my project"
• User says "I want the same setup as [reference project]" or similar
• User asks "configure AI assistants for this repo"

Prerequisites

• The project must have a master document describing what the project is, its stack, architecture, and objectives
• If none exists, this skill guides the user to create one (Phase 0)

---

EXECUTION FLOW — 8 PHASES

---

PHASE 0: INITIAL DISCOVERY

0.1 — Locate the master document

Ask the user:

"What is the master document for your project? (the file that describes the stack, architecture, and objectives). It can be a .md, .txt, or any document."

Suggest common options:

• PROJECT_CONTEXT.md
• README.md
• ARCHITECTURE.md
• PRD.md (Product Requirements Document)
• SYSTEM_PROMPT.md
• Any other the user indicates

0.2 — If no master document exists

Guide the user through an interview to create one. Ask these questions (adapt phrasing to context):

1. Project type: Web app, API, mobile, data pipeline, CLI tool, library, game, embedded, etc.?
2. Technology stack: Languages, frameworks, databases, message queues, caches
3. Architecture: Monolith, modular monolith, microservices, serverless, event-driven, CQRS, etc.?
4. Team size: Solo, small team (2-5), medium (6-15), large (15+)?
5. Main modules/components: List the core feature areas
6. External integrations: Third-party APIs, SaaS platforms, payment providers?
7. Testing strategy: Unit, integration, E2E? Which frameworks?
8. Security requirements: Auth method, compliance needs (SOC2, HIPAA, GDPR)?
9. Infrastructure: Cloud provider, container orchestration, CI/CD platform?
10. Deployment targets: Staging/production environments, CDN, edge?

With the answers, generate a PROJECT_CONTEXT.md at the repository root.

0.3 — Analyze the master document

Read the master document completely and extract:

• Stack: Languages, frameworks, databases, infrastructure tools
• Architecture: Patterns, module boundaries, data flow
• Modules: Core components and their responsibilities
• Integrations: External services and APIs
• Security posture: Auth mechanisms, compliance requirements
• Testing approach: Frameworks, coverage expectations
• Team structure: Roles, collaboration patterns

Store this analysis in memory for use across all subsequent phases.

---

PHASE 1: IDE DETECTION

1.1 — Detect active IDE(s)

Search the filesystem in this priority order:

| IDE / Tool | Detection Signals | Config Paths | |---|---|---| | Cursor | .cursor/ dir, .cursorrules file, .cursor/mcp.json | .cursor/, .cursorrules | | Claude Code | .claude/ dir, CLAUDE.md file, .claude/settings.json | .claude/, CLAUDE.md | | VS Code + Continue | .vscode/ dir AND .continue/ dir | .continue/, .vscode/ | | VS Code + Cline | .vscode/ dir AND .clinerules file | .clinerules | | Windsurf | .windsurf/ dir, .windsurfrules file | .windsurf/, .windsurfrules | | GitHub Copilot | .github/copilot-instructions.md | .github/ | | Aider | .aider.conf.yml or .aiderignore | .aider.conf.yml | | Zed + Assistant | .zed/ dir | .zed/settings.json |

Reference: detectors/ide-detector.md for full detection logic.

1.2 — Handle multiple IDEs

If multiple IDEs are detected, configure ALL of them. Ask the user which is primary.

1.3 — Record results

Store:

• Primary IDE detected
• Secondary IDEs detected
• Configuration paths for each

---

PHASE 2: STACK DETECTION AND PROFILE SELECTION

2.1 — Analyze the master document for technology signals

Use detectors/stack-detector.md for exhaustive technology-to-profile mapping.

Core mapping table:

| Technology Detected | Required Profile(s) | |---|---| | .NET, C#, ASP.NET Core | backend-architect (.NET) | | Java, Spring Boot, Quarkus | backend-architect (Java) | | Python, Django, FastAPI, Flask | backend-architect (Python) | | Node.js, Express, NestJS, Fastify | backend-architect (Node) | | Go, Gin, Echo, Fiber | backend-architect (Go) | | Rust, Actix, Axum | backend-architect (Rust) | | React, Vue, Angular, Svelte, Solid | frontend-engineer | | React Native, Flutter, Swift, Kotlin | mobile-engineer | | PostgreSQL, MySQL, MongoDB, Redis | database-admin | | Docker, Kubernetes, Terraform, Pulumi | infra-devops | | Any testing mention | qa-lead | | AI/ML, LLM, RAG, embeddings | ai-engineer | | Auth, Security, OWASP, compliance | security-specialist | | Figma, Design System, Storybook | design-engineer | | ETL, Spark, Airflow, dbt | data-engineer | | Blockchain, Solidity, Web3 | blockchain-engineer | | Unity, Unreal, Godot | game-engineer |

Reference: detectors/profile-detector.md for complete mapping with sub-specializations.

2.2 — Present detected profiles to the user

Format:

Based on your project, I detect these profiles are needed:
1. ✅ backend-architect (.NET)
2. ✅ frontend-engineer (React/TypeScript)
3. ✅ database-admin (PostgreSQL)
4. ✅ infra-devops (Docker + GitHub Actions)
5. ✅ qa-lead
6. ✅ security-specialist
7. ❓ ai-engineer (detected AI mentions — do you need it?)

Would you like to add or remove any?

2.3 — Wait for user confirmation before continuing

NEVER auto-generate agents without explicit approval of the profile list.

---

PHASE 3: SUB-AGENT CREATION

For each confirmed profile:

3.1 — Load templates and references

1. Read templates/agent-template.md for the structural skeleton
2. Read the relevant profile catalog from profiles/{category}.md
3. Read profiles/certifications-registry.md for certification names

3.2 — Generate the sub-agent

Each sub-agent MUST contain these sections:

# {ROLE_NAME}

## Profile
{Senior/Staff/Principal} {Title} specialized in {Stack}

## Certifications and frameworks mastered
{Minimum 5, from certifications-registry.md}
{Only those relevant to the project's stack}
{Each certification uses its official, verifiable name}

## Scope
{Directories and files under this agent's authority}

## Responsibilities
{8-12 specific, actionable responsibilities}

## Strict technical rules
{Minimum 10 concrete, verifiable, stack-specific rules}
{NOT generic — each rule must reference a technology or pattern}

## Workflow when receiving a task
1. Read the project's master document for context
2. Explore existing codebase to detect established patterns
3. If a similar pattern exists → follow it exactly
4. If no pattern exists → propose one and wait for approval
5. Implement COMPLETE code (never placeholders)
6. Verify it compiles/runs without errors
7. Include happy-path tests at minimum
8. Document per HANDOFF_PROTOCOL

## Anti-patterns (NEVER do)
{Minimum 5 anti-patterns specific to the role and stack}

## Handoff
When I produce work another agent will consume, I document:
{What this agent documents for the next agent}

3.3 — Certification rules

• Every certification MUST be real and verifiable
• Use official names exactly as they appear in profiles/certifications-registry.md
• Include ONLY certifications relevant to the detected stack
• Minimum 5, maximum 12 per agent

3.4 — Write files to ALL detected IDE locations

For each agent, create:

• .cursor/agents/{role-name}.md (if Cursor detected)
• .claude/agents/{role-name}.md (if Claude Code detected)
• Other IDE-specific locations as applicable

3.5 — Create README.md and HANDOFF_PROTOCOL.md

Use templates/handoff-protocol-template.md as base and references/handoff-protocol-real-example.md as quality reference. Adapt to the project's stack, modules, and team structure. Place in the same directories as the agents.

---

PHASE 4: PLAYBOOK CREATION

4.1 — Operational Playbook

Using templates/playbook-operations.md as base and references/playbook-operations-real-example.md as quality reference, generate a playbook that includes:

• Rule 1: Mandatory context (read master document + rules before ANY code)
• Rule 2: Sub-agent table with when to invoke each one
• Rule 3: Available skills
• Rule 4: Handoff protocol summary
• Rule 5: Existing patterns rule
• Rule 6: Completeness rule (no placeholders ever)
• Additional project-specific rules as needed

4.2 — Strategic Playbook

Using templates/playbook-strategy.md as base and references/playbook-strategy-real-example.md as quality reference, generate:

• Product/project vision
• Architecture and stack summary table
• Module map with dependencies (ASCII diagram if possible)
• Implementation phases with deliverables
• Architecture Decision Records (ADRs) inferred from the master document
• Quality gates (pre-commit, pre-PR, CI, pre-deploy, post-deploy)
• Non-functional requirements
• Naming and git conventions

4.3 — Memory Playbook

Using templates/playbook-memory.md as base, generate:

# Memory Playbook — {Project Name}

## Decisions made
(Updated during development)
- [DATE] Decision: ... Reason: ...

## Problems encountered and solutions
(Updated during development)
- [DATE] Problem: ... Solution: ...

## Established patterns
(Updated when a new pattern is created)
- Pattern: ... Location: ... Use when: ...

## Module dependencies
(Extracted from master document)
- Module A depends on B because...

## Context for future sessions
(Information any new session needs to know)
- ...

4.4 — Place playbooks in correct IDE locations

| IDE | Playbook Location | |---|---| | Cursor | .cursor/rules/ | | Claude Code | .claude/ | | VS Code + Continue | .continue/ | | Windsurf | .windsurf/rules/ | | General | docs/playbooks/ (always, as fallback) |

---

PHASE 5: IDE RULES CONFIGURATION

5.1 — Determine which rules file to use

| IDE | Rules File | |---|---| | Cursor | .cursorrules (root) | | Claude Code | CLAUDE.md (root) | | Windsurf | .windsurfrules (root) | | VS Code + Cline | .clinerules (root) | | GitHub Copilot | .github/copilot-instructions.md | | Continue | .continue/config.json |

5.2 — If the file already exists

• Read it completely
• DO NOT overwrite it
• Append missing sections at the end
• Preserve ALL existing content

5.3 — If the file does not exist

Create it using templates/cursorrules-template.md or templates/claude-rules-template.md adapted to the IDE format and the project's stack. Use references/cursorrules-real-example.md as the quality reference for depth, structure, and enforcement language.

5.4 — Mandatory pre-execution instruction

The rules file MUST include this instruction (adapted to the IDE's format):

BEFORE EVERY RESPONSE IN THIS PROJECT:
1. Read the project master document: {MASTER_FILE_NAME}
2. Read the operational playbook: {PLAYBOOK_PATH}
3. Identify which sub-agent(s) apply: {AGENTS_PATH}
4. Check if relevant skills are installed
5. Follow the rules of the corresponding sub-agent
6. Consult the memory playbook for context

This ensures the LLM ALWAYS reads the guide before every execution, without the user having to remind it.

---

PHASE 6: SKILL SEARCH AND INSTALLATION

6.1 — Determine needed skills from the master document

Technology-to-skill search mapping:

| Detected Stack | Skills to Search | |---|---| | .NET / C# | "dotnet", "csharp", "aspnet", "ef-core" | | React | "react", "typescript", "vite", "tailwind" | | Python | "python", "django", "fastapi", "flask" | | PostgreSQL | "postgresql", "database", "sql" | | Docker / K8s | "docker", "kubernetes", "container" | | Testing | "testing", "playwright", "jest", "vitest" | | CI/CD | "github-actions", "gitlab-ci", "azure-devops" | | AI / ML | "openai", "langchain", "rag", "llm" | | Security | "owasp", "security", "auth" | | Design | "shadcn", "tailwind", "storybook" |

Reference: detectors/stack-detector.md for the complete mapping.

6.2 — Execute searches

If find-skills is available, execute searches for each needed skill. If not available, list recommended skills with manual installation commands.

6.3 — Present results table

| Skill | Relevance | Install? |
|-------|-----------|----------|
| react-patterns | High — React 19 detected | Yes |
| shadcn | High — shadcn/ui in deps | Yes |
| playwright-best-practices | Medium — E2E mentioned | Recommended |
| openai-api | Low — no AI features yet | Optional |

6.4 — Wait for approval before installing

NEVER install skills without user confirmation.

---

PHASE 7: MCP DETECTION AND CONFIGURATION

7.1 — Detect external services from the master document

Reference: detectors/mcp-detector.md for the complete service-to-MCP mapping.

Core mapping:

| Service Detected | Recommended MCP | |---|---| | GitHub / GitLab | server-github / server-gitlab | | Jira | jira MCP (community) | | Notion | server-notion | | Slack | server-slack | | PostgreSQL | server-postgres | | MongoDB | (community MCP) | | AWS | server-aws-kb-retrieval | | Google Drive | server-gdrive | | Filesystem | server-filesystem | | Web access | server-fetch / server-puppeteer | | Supabase | server-supabase | | Redis | (community MCP) |

7.2 — Determine installation method

If multi-mcp-connector skill is available → delegate installation to it. If not → generate the MCP JSON entries manually and present them.

7.3 — Handle API keys safely

For MCPs requiring API keys or tokens, NEVER request the actual values. Instead, add the MCP entry with a placeholder and notify the user:

⚠️ MCPs requiring manual API key configuration:
1. notion → NOTION_API_KEY → Get at https://notion.so/my-integrations
2. github → GITHUB_TOKEN → Get at https://github.com/settings/tokens
3. slack → SLACK_BOT_TOKEN → Get at https://api.slack.com/apps

After bootstrap, edit your mcp.json and add the keys.

7.4 — Create MCP_SETUP_GUIDE.md

Generate a file at the project root with step-by-step instructions for obtaining each required API key, including:

• Service name and URL
• Required permissions/scopes
• Where to place the key (env var or config file)
• How to verify the connection works

---

PHASE 8: VALIDATION AND REPORT

8.1 — Run validation checklist

Execute the full checklist from validators/bootstrap-validator.md:

BOOTSTRAP VALIDATION CHECKLIST
═══════════════════════════════
[ ] Master document read and analyzed
[ ] IDE(s) detected
[ ] Profiles confirmed with user
[ ] Sub-agents created in correct locations
[ ] Sub-agents identical between .cursor/ and .claude/ (if both exist)
[ ] Operational playbook created
[ ] Strategic playbook created
[ ] Memory playbook created
[ ] IDE rules configured with mandatory pre-execution reading
[ ] Skills searched/installed (or listed for manual installation)
[ ] MCPs detected and configured (or listed with guide)
[ ] BOOTSTRAP_LOG.md generated
[ ] No secret or API key exposed in committable files
[ ] .gitignore updated to exclude local agent configs if needed

8.2 — Generate BOOTSTRAP_LOG.md

Create at the repository root:

# Bootstrap Log — {Project Name}
## Generated on: {date}
## Skill: project-bootstrap-architect

### Master document analyzed
- {name}: {2-line summary}

### IDE detected
- Primary: {IDE}
- Secondary: {list}

### Sub-agents created ({count})
| Agent | Profile | Certifications | Location |
|-------|---------|----------------|----------|
| ... | ... | {count} | .cursor/agents/, .claude/agents/ |

### Playbooks created
- Operational: {path}
- Strategic: {path}
- Memory: {path}

### Rules configured
- {file}: {what was added}

### Skills installed
| Skill | Status |
|-------|--------|
| ... | installed / recommended / manual |

### MCPs configured
| MCP | Status | API Key Required |
|-----|--------|-----------------|
| ... | configured / needs-key | yes/no |

### Files created
{complete list of all files created}

### Files modified
{complete list of files modified with what was added}

### Warnings
- {any issues found during bootstrap}

8.3 — Present summary and ask

"Bootstrap complete. Would you like me to run a detailed verification of each component?"

---

CRITICAL RULES

1. NEVER overwrite existing files without explicit user confirmation
2. NEVER invent certifications — only use those from profiles/certifications-registry.md
3. NEVER expose secrets or API keys in committable files
4. ALWAYS ask profile confirmation before creating agents
5. ALWAYS create in ALL detected IDE locations when multiple are detected
6. ALWAYS generate BOOTSTRAP_LOG.md as an auditable record
7. ALWAYS update .gitignore to exclude local-only agent configs if needed
8. ALWAYS leave playbooks with editable sections for updates during development
9. If multi-mcp-connector exists, use it. If not, don't fail — generate configs manually
10. If find-skills is unavailable, don't fail — list recommended skills for manual installation
11. Every sub-agent must have minimum: 5 certifications, 10 technical rules, 5 anti-patterns
12. Playbooks must reference the master document — never hardcode project specifics that might change

---

REAL-WORLD REFERENCES

The references/ directory contains REAL production examples from an actual project. Use these as the quality bar and structural reference when generating outputs. They are NOT templates — they are finished products showing what professional output looks like.

| Reference File | What It Demonstrates | |---|---| | references/cursorrules-real-example.md | Complete .cursorrules with 13 sections, naming conventions, code quality rules, project structure trees, API patterns, testing requirements, and skills catalog | | references/playbook-operations-real-example.md | Operational playbook with 9 rules: context, agents table, skills, handoff, patterns, completeness, RAG, MCPs, bootstrap | | references/playbook-strategy-real-example.md | Strategic playbook with module dependency map, full stack tables with versions, 6 implementation phases, 14 ADRs, 5 quality gates, NFR table, module pattern, port conventions, git conventions | | references/handoff-protocol-real-example.md | Handoff protocol with 5 agent-to-agent templates, typed handoff documents, 6-step delivery sequence, and security review gate |

How to use references

1. Before generating .cursorrules → Read references/cursorrules-real-example.md to match the depth, structure, and enforcement language
2. Before generating playbook-operations → Read references/playbook-operations-real-example.md to match the rule format and agent table structure
3. Before generating playbook-strategy → Read references/playbook-strategy-real-example.md to match the module map, stack tables, phases, ADRs, quality gates, and conventions
4. Before generating HANDOFF_PROTOCOL → Read references/handoff-protocol-real-example.md to match the template-driven, producer/consumer handoff pattern

Each reference file ends with a "Key Patterns to Extract" section listing the 10 most important structural patterns to replicate.