Start — Project Bootstrap Skill

Overview

Uses a 6-module framework to progressively transform a vague project idea into a complete set of bootstrap documents. Adapted from the prompt-architect 8-module pattern.

Without these documents, the Sentinel maintenance pipeline cannot operate:

• §4.2 compaction needs ARCHITECTURE.md as output target

• §4.3 routing needs PRD.md to judge which tools are relevant

• §4.4 chain-triggers need directory CLAUDE.md to sync against

Language Behavior

Default to English. If the user writes in Chinese, respond in Chinese. Match the user's language throughout the session.

8-Module Framework

Module Core Question Output Target

1 Project Identity What is this? Who is it for? What problem does it solve? PRD.md §1

2 Core Requirements What must it do? Priority? Acceptance criteria? PRD.md §2-3

3 Use Cases What are the key user flows? Happy path + edge cases? PRD.md §4

4 Assumptions & Dependencies What do we assume to be true? What do we depend on? PRD.md §5

5 Constraints & Non-Goals What is out of scope? Known limitations? Risks? PRD.md §6

6 Tech Stack What languages, frameworks, external services? ARCHITECTURE.md §1

7 Architecture & Module Boundaries How are components organized? ARCHITECTURE.md §2-3

8 Development Workflow & Quality How does the team work? What standards? CLAUDE.md rules

Optional module (ask only if applicable):

Module Core Question Output Target

M Metrics & Targets What quantifiable success looks like? PRD.md §7

Applicability: skip for research prototypes / personal experiments. Ask for production apps / team projects.

Process

Phase 1: Intake and Quick Diagnosis

Sentinel-Aware Scanning

Before scanning, check for .sentinel/manifest.json :

• If found: read the sentinel_owned and start_scan_excluded arrays

• Exclude all listed paths from the diagnostic scan — these are pre-installed Sentinel SDK infrastructure (tests, docs, manifests), NOT the user's project

• Do NOT infer project identity, tech stack, or architecture from excluded paths

• .sentinel/ and .claude/ are always excluded (framework internals)

• If .sentinel/manifest.json does not exist: scan everything (non-Sentinel project)

This ensures /start sees a clean slate in Sentinel-initialized projects while still detecting user-created files correctly.

File Detection

Read existing project files (respecting exclusions above) to detect what already exists:

• PRD.md — if exists, this is an UPDATE, not a fresh start

• ARCHITECTURE.md — if exists, preserve and update

• CLAUDE.md — if exists, preserve human rules

• progress.yaml — if exists, preserve constraints

• README.md — may contain project context (skip if in sentinel_owned )

• docs/ — may contain design documents (skip sentinel-owned paths within)

• Source code directories — may indicate existing architecture (skip .sentinel/ , .claude/ )

Output a diagnostic table:

Project Bootstrap Diagnostic

Status criteria:

• Covered: Sufficient information exists in project files

• Partial: Some information exists but incomplete

• Missing: Not documented anywhere

Phase 2: Applicability Assessment

Not every module needs full elicitation. Assess based on project maturity:

Project State Typical Approach

Empty directory Full 8-module interview

Existing code, no docs Extract from code first, label items as inferred vs confirmed, run confirmation pass with user

Existing docs, incomplete Fill gaps only

Full docs, re-bootstrap Validate and update

Use AskUserQuestion to confirm assessment:

I've analyzed your project. Here's what I found and what's missing. [diagnostic table]

I recommend focusing on modules [X, Y, Z]. Does this match your priorities? Also — is there any context I should know that isn't in the files?

Phase 3: Module-by-Module Completion

For each module with status "Missing" or "Partial", use AskUserQuestion to fill gaps.

Question priority (highest to lowest):

• Module 1 — Project Identity (everything else depends on this)

• Module 2 — Core Requirements (defines what the project must do)

• Module 3 — Use Cases (makes requirements concrete and testable)

• Module 4 — Assumptions & Dependencies (surfaces hidden premises)

• Module 5 — Constraints & Non-Goals (prevents scope creep)

• Module 6 — Tech Stack (constrains architecture choices)

• Module 7 — Architecture (module boundaries)

• Module 8 — Workflow (generates CLAUDE.md rules)

• Module M — Metrics (optional, only for production/team projects)

Questioning strategy:

• Maximum 4 questions per round (AskUserQuestion limit)

• Each question provides 2-4 options plus custom

• If user says "you decide" or "not sure", suggest a reasonable default and confirm

• When answers are vague, use example-driven follow-ups ("Can you give me an example of how a user would do X?")

• After each round, update diagnostic table

Quality gate before finalizing PRD:

• Each requirement must have: actor + action + acceptance criterion

• If any requirement lacks acceptance criteria, ask a follow-up

• If overall confidence is low, output "Draft PRD" (not "Final PRD") and list unresolved questions

Module-specific question templates:

Module 1 — Project Identity

• "Describe your project in one sentence" — Open-ended

• "What problem does this project solve? For whom?" — Open-ended

• "Who is the primary user?" — Options: Developer / End user / Research audience / Internal team

• "What is the project scope?" — Options: Library/toolkit / Web application / CLI tool / Research prototype / Other

Module 2 — Core Requirements

• "List 3-5 things this project MUST do" — Open-ended

• "Which of these are MUST-have vs SHOULD-have vs COULD-have?" — Prioritization (MoSCoW)

• "What is the primary deliverable?" — Options: Working software / Research paper + prototype / API / Documentation + templates

• "What does 'done' look like for v1?" — Open-ended

Module 3 — Use Cases

• "Describe the main user flow (happy path): user does X → system does Y → outcome Z" — Open-ended

• "What could go wrong? Any edge cases to handle?" — Open-ended

• "For each MUST requirement, what is the acceptance test?" — One per requirement

If user gives minimal answers, propose use cases based on requirements and ask for confirmation.

Module 4 — Assumptions & Dependencies

• "What do you assume to be true that, if wrong, would change the approach?" — Open-ended

• Examples: "OAuth provider supports refresh tokens", "Data fits in memory", "Users have modern browsers"

• "What external systems does this project depend on?" — Open-ended

• Examples: PostgreSQL, third-party APIs, specific OS, specific hardware

• "Any dependency that might change or become unavailable?" — Open-ended

Label each item as confirmed (verified) or assumed (needs validation). Assumed items are candidates for future progress.yaml verification.

Module 5 — Constraints & Non-Goals

• "What is explicitly OUT of scope for v1?" — Open-ended

• "Any known technical limitations?" — Options: No auth needed / No real-time / No mobile / Other

• "Any risks that could derail the project?" — Open-ended (merge risks into constraints as "constraint that might appear")

Module 6 — Tech Stack

• "Primary language?" — Options: Python / TypeScript / Go / Rust / Other

• "Key frameworks or libraries?" — Open-ended (suggest based on project type)

• "External services or APIs?" — Options: Database / Cloud APIs / MCP servers / CLI tools / None

• "Package manager?" — Options: pip/uv / npm/bun / cargo / Other

Module 7 — Architecture

Based on confirmed requirements, use cases, and tech stack, PROPOSE an initial architecture:

• Module breakdown (top-level directories and their responsibilities)

• Key interfaces between modules

• Data flow overview

Ask user to confirm, modify, or reject the proposal.

Module 8 — Workflow & Quality

• "Testing approach?" — Options: Unit tests required / Integration tests / Manual testing / TDD

• "Code style preferences?" — Open-ended (or extract from existing CLAUDE.md)

• "Any tools or conventions the AI agent should always follow?" — Open-ended

• "Commit/PR workflow?" — Options: Direct to main / Feature branches / PR required

Module M — Metrics (optional)

Ask ONLY if project is production/team-facing. Skip for research prototypes.

• "What does success look like, quantitatively?" — Open-ended

• "Any performance targets?" — Options: Response time / Throughput / Availability / Not applicable

• "Current baseline for comparison?" — Open-ended or "N/A (greenfield)"

Phase 4: Generate Documents

Once all applicable modules reach "Covered", generate the bootstrap documents.

4a. PRD.md

Use status: draft if quality gate found unresolved questions. Use status: v1.0 if all requirements have acceptance criteria.

project: {name} version: v1.0 # or "draft" if quality gate has unresolved items created_at: {YYYY-MM-DD} updated_at: {YYYY-MM-DD}

{Project Name} — Product Requirements Document

1. Project Identity

• Name: {name}
• Problem statement: {what problem this solves, from Module 1}
• Target user: {user}
• Scope: {scope}

2. Core Requirements

3. Deliverables

• Primary deliverable: {from Module 2}
• v1 definition of done: {from Module 2}

4. Key Use Cases

UC1: {use case name}

Actor: {who} Flow: {step 1 → step 2 → outcome} Edge cases: {what could go wrong}

UC2: {use case name}

...

5. Assumptions and Dependencies

Assumptions (must remain true for this approach to work)

Dependencies (external systems this project relies on)

6. Constraints and Non-Goals

Non-Goals (explicitly out of scope for v1)

{From Module 5}

Known Limitations

{From Module 5}

Risks

{From Module 5 — constraints that might appear in the future}

7. Metrics and Targets (optional)

{Only if Module M was applicable. Otherwise: "N/A — research prototype / personal project."}

8. Success Criteria

{Derived from requirements acceptance criteria + metrics if applicable}

Changelog

Unresolved Questions

{List any items that could not be resolved during the interview. Only present if status is "draft".}

4b. ARCHITECTURE.md

{Project Name} — Architecture

1. Tech Stack

• Language: {from Module 3}
• Frameworks: {from Module 3}
• External services: {from Module 3}
• Package manager: {from Module 3}

2. Module Structure

{From Module 4 — table of top-level directories + responsibilities}

3. Data Flow

{From Module 4 — how data moves between modules}

4. Constraints

{From Module 5 — technical limitations that affect architecture}

4c. CLAUDE.md (root, prescriptive rules)

{Project Name}

Architecture and stack: see ARCHITECTURE.md Requirements: see PRD.md

Rules

{From Module 6 — testing, style, conventions} {From existing CLAUDE.md if present — preserve human rules}

Workflow

{From Module 6 — commit, PR, CI conventions}

4d. progress.yaml (machine-readable intake funnel)

schema_version: 1 entries:

• date: "{TODAY'S DATE}" title: Project initialized status: unprocessed session_report: "" next_steps:
  • Run /routing to select project tools candidates: []

Phase 5: Set Up Directory Structure and Activate Sentinel

Based on the architecture from Module 4:

• Create the module directories listed in ARCHITECTURE.md

• Create directory CLAUDE.md manifests for each module (AI-managed, initially minimal)

• Create review/ directory for review reports

• Ensure .claude/skills/ and .claude/rules/ exist

5a. Install git hooks (automatic)

Run: bash .sentinel/hooks/install.sh

This is low-risk and idempotent. Execute without asking. If .git/ doesn't exist yet, skip and note: "Hooks will be installed after git init ."

5b. Backfill YAML front matter for existing source files (requires confirmation)

Scan the project for .py , .ts , .js , .sh files without YAML front matter. If found:

• Show summary: "Found N source files without YAML headers. Shall I add front matter?"

• Use AskUserQuestion to confirm

• If approved: generate headers for each file (input /output /pos /last_modified )

• If declined: skip, note in progress.yaml as a future task

5c. Create directory manifests for existing code directories (requires confirmation)

Scan the project for directories containing source files but no CLAUDE.md . If found:

• Show summary: "Found N directories without manifests. Shall I create them?"

• Use AskUserQuestion to confirm

• If approved: generate directory CLAUDE.md for each

• If declined: skip

Phase 6: Confirm Activation

Tell the developer:

• PRD.md, ARCHITECTURE.md, CLAUDE.md, progress.yaml are ready

• Directory structure is created

• Git hooks are installed (soft warnings on commit)

• [If backfill was done] N source files now have YAML front matter

• [If manifests were created] N directory manifests created

• Chain-trigger pipeline is now active (auto-updates headers and manifests on code changes)

• Next step: run /routing to scan available tools and select what this project needs

• After routing: run /boundary to generate boundary declarations

Sentinel is now operational. All maintenance pipelines are active.

If Updating Existing Documents

• PRD.md exists: Show diff of proposed changes, ask for confirmation before overwriting

• ARCHITECTURE.md exists: Merge new information, preserve existing module descriptions

• CLAUDE.md exists: NEVER overwrite human rules; only append new rules from Module 6 at the end

• progress.yaml exists: NEVER modify; constraints are sacred

Anti-Patterns

Do Not Do Instead

Generate PRD without asking the user Interview first, generate from answers

Assume architecture from project name alone Ask about requirements + use cases before proposing architecture

Overwrite existing CLAUDE.md rules Preserve and append

Skip Module 5 (constraints) Non-goals prevent scope creep — always ask

Skip Module 4 (assumptions) Unchecked assumptions are the #1 source of context degradation

Generate all docs before user confirms architecture Propose architecture in Module 7, wait for confirmation

Propose architecture without knowing tech stack Module 6 before Module 7, always

Accept vague requirements without acceptance criteria Use example-driven follow-ups to make them testable

Treat code-extracted info as confirmed Label as inferred, run confirmation pass with user

Output "Final PRD" when questions are unresolved Use "Draft PRD" with Unresolved Questions section

Force Module M (Metrics) on research projects Skip unless production/team project