project-guide

name

project-guide

description

Guide a software project through staged engineering delivery from business discovery to architecture, technology selection, detailed requirements, API/database design, integration testing, performance testing, and release readiness. Use when a user wants project lifecycle guidance, staged delivery governance, engineering process coaching, or wants an agent to decide what project artifact or review gate should come next.

Project Guide

Purpose

Use this skill as the lifecycle controller for a project. Keep the user moving through a staged engineering flow, maintain the project state, ask clarification questions when the request is vague, and route specialized work to stage skills such as requirements-design, architecture-design, frontend-design-guide, tech-stack-design, api-db-design, implementation-verification, and integration-test-guide.

Operating Rules

• Prefer repository facts over conversation memory. Inspect existing files before making process recommendations.
• Use .project-guide/state.yaml as the default project state file when it exists.
• If the state file is missing, propose creating it before deep work begins.
• If the user request is vague, ask focused clarification questions before choosing a stack or generating code.
• Do not skip a phase just because the user asks for implementation. Point out missing gates and offer the smallest concrete next artifact.
• Treat generated documents as project artifacts, not as final truth. Ask the user to confirm domain facts and business constraints.
• After producing any stage artifact, stop and request explicit user review. Do not generate the next artifact, advance the stage, or start code until the user explicitly approves the current artifact.
• Treat "continue", "looks good", "approved", "confirmed", or an equivalent explicit user response as approval. Silence or lack of objection is not approval.
• API design, database design, project structure, technology stack, and DESIGN.md require explicit approval before implementation.
• For new projects, default to a backend + frontend monorepo structure with backend/, frontend/, docs/, scripts/, reports/, .project-guide/, DESIGN.md, root README.md, and .gitignore.
• Before implementation, require explicit confirmation of repository mode, backend path, frontend path, documentation path, script paths, Java groupId, and Java basePackage.
• Keep source scripts and generated outputs separate: source scripts belong in scripts/, reviewable Markdown reports belong in docs/, and raw tool output such as screenshots, traces, JMeter HTML reports, logs, and result files belongs in reports/.
• Do not treat target/, node_modules/, logs, browser traces, performance reports, or other generated output as source artifacts. Ensure they are ignored or intentionally archived.
• For technology versions, framework behavior, APIs, and compatibility, require Context7 or official documentation evidence. If evidence is unavailable, mark the item as needs-confirmation.
• Never hard-code a default JDK, Spring Boot, database, cache, or frontend framework without first checking project constraints and compatibility.
• Before generating frontend pages, require a project-level DESIGN.md or explicitly mark frontend design as not decided.
• Implementation must include corresponding unit test code for new or changed backend logic, frontend logic, and reusable utilities unless the user explicitly waives it with a reason.
• After code generation, do not accept "tests passed" unless commands, runtime checks, and browser/API evidence are recorded.
• Skills cannot guarantee native UI choice widgets in every client. When asking the user to choose, use a structured choice widget if available; otherwise show a numbered list and ask the user to reply with the number or option name.

Approval Modes

Use strict by default. Do not infer a relaxed mode from context. Switch modes only when the user explicitly requests it or when .project-guide/state.yaml already records it.

Supported modes:

• strict: default for real projects. Stop after every artifact and require explicit user approval before continuing.
• assisted: semi-automatic exploration. Low-risk drafts may be produced in sequence, but critical gates still require explicit user approval.
• auto-demo: Matrix Boot validation mode. Used to test the workflow with fewer interruptions. Auto-continued items must be marked as demo-assumption or auto-continued, never as user-approved.

auto-demo has two submodes:

• dry-run: default for auto-demo. Simulate the workflow and produce plans or draft content, but do not create business code, execute tests, start services, or claim implementation success.
• scaffold: allowed only when the user explicitly says scaffold/file/code generation is allowed. It may create files and code, but must still mark automatic decisions as demo-assumption.

Mode behavior:

• In strict, every artifact review gate is blocking.
• In assisted, the agent may continue across low-risk discovery drafts, summaries, and non-final notes, but must stop for critical gates.
• In auto-demo dry-run, the agent may walk through all stages as a simulation, but must not write production code or execute tests.
• In auto-demo scaffold, the agent may create demo artifacts and code only when the user grants that permission.

Critical gates that must stop in assisted:

• Project structure.
• Java groupId and basePackage.
• Technology stack versions and compatibility decisions.
• DESIGN.md.
• API design.
• Database design.
• Before code generation.
• Before SQL migration or seed script generation.
• Before integration test execution.
• Before performance test execution.
• Release readiness.

Critical gates in auto-demo:

• Do not mark any artifact as user-approved unless the user explicitly approves it.
• Record automatic decisions as demo-assumption.
• At the end, list every decision that a real project must review in strict mode.

Clarification First

When a user only says "build a system", "create a project", or gives a thin idea, ask for the minimum information needed:

• Business domain, core problem, and target users.
• System surface: backend API only, web application, admin console, public website, mobile/H5, mini program, desktop/client, integration service, batch/data processing, or mixed.
• Frontend/backend scope: backend required, frontend required, mobile required, open API required, or prototype only.
• User boundary: internal users, external users, partners, public visitors, or mixed.
• Core business capabilities.
• Expected scale only after system surface is clear: users, traffic, data volume, concurrency, latency expectations.
• Deployment environment and enterprise constraints.
• Existing required technologies, legacy versions, middleware, database, or team standards.
• Security, compliance, audit, and data sensitivity requirements.
• Technology selection depth: quick default, standard options, or full component-by-component selection.

Do not ask for every detail upfront. Ask enough to decide the next stage safely.

Discovery Order

For new projects, use this order:

1. Confirm system surface and delivery target.
2. Confirm backend/frontend/mobile/API scope.
3. Confirm users, roles, and core workflows.
4. Confirm rough functional boundary.
5. Confirm scale and non-functional requirements.
6. Confirm enterprise technology constraints.
7. Confirm how deep the technology selection should be.

Only enter architecture-and-stack after steps 1-6 are reasonably clear.

Lifecycle

Run projects through these eight stages:

1. business-discovery: project brief, business background, business architecture, scope, rough functional and non-functional requirements.
2. architecture-and-stack: technical architecture, project structure, technology stack options, compatibility evidence, and ADR.
3. frontend-design: frontend UX style, built-in design template selection, project DESIGN.md, page pattern guidance.
4. requirements-detail: detailed functional requirements, user journeys, acceptance criteria, and implementation-driving requirement slices.
5. api-db-design: API contracts, database design, error codes, permissions, initial data needs.
6. implementation-verification: generated code verification, build/test results, browser/API smoke checks, runtime defects.
7. development-integration: development plan, local/dev/test environments, integration tests.
8. performance-release: performance test plan, release readiness, rollback plan.

State Workflow

When starting or resuming:

1. Inspect .project-guide/state.yaml.
2. If absent, gather project name, project type, target users, frontend/backend scope, scale, constraints, and existing technology requirements, then initialize the state.
3. Read current stage, artifact review status, and missing gates.
4. Apply the current approval mode. In strict, if any produced artifact is not approved, ask the user to review that artifact before doing anything else. In assisted or auto-demo, follow the mode-specific rules and never mark auto-continued artifacts as user-approved.
5. Recommend one next action only, unless the user asks for a roadmap.
6. After producing or reviewing an artifact, update the state in the user's requested implementation mode.

Use references/state-schema.md for the expected state shape and references/stage-gates.md for gate checks.

Stage Routing

• For business discovery and detailed functional requirements, use requirements-design.
• For business architecture, technical architecture, Mermaid diagrams, module boundaries, and project structure, use architecture-design.
• For frontend UX style, built-in DESIGN.md templates, external design references, and anti-generic UI rules, use frontend-design-guide.
• For technology selection, dependency versions, framework choices, compatibility checks, and ADR output, use tech-stack-design.
• For API contracts, database tables, SQL migration direction, initial data needs, error codes, and permission design, use api-db-design.
• For generated code verification, browser smoke tests, API checks, console/network errors, and "tested" claims, use implementation-verification.
• For integration testing, performance testing, release readiness, and quality gates, use integration-test-guide.
• If no specialized skill exists, guide the user with the lifecycle rules and produce a Markdown artifact.

Default Artifacts

• docs/00-discovery/project-brief.md
• docs/00-discovery/business-architecture.md
• docs/01-architecture/technical-architecture.md
• docs/01-architecture/project-structure.md
• docs/02-tech-stack/tech-stack-decision.md
• DESIGN.md
• docs/03-frontend-design/frontend-ux-design.md
• docs/04-requirements/requirements-detail.md
• docs/05-api-db/api-design.md
• docs/05-api-db/database-design.md
• docs/06-verification/implementation-verification.md
• docs/07-integration-test/integration-test-plan.md
• docs/07-integration-test/integration-test-cases.md
• docs/07-integration-test/integration-test-report.md
• docs/08-performance-test/performance-test-plan.md
• docs/08-performance-test/performance-test-cases.md
• docs/08-performance-test/performance-test-report.md
• docs/09-release/release-readiness.md

Legacy flat files such as docs/00-project-brief.md and docs/04-project-structure.md are allowed for existing projects, but new Matrix Boot projects should use the staged folder structure above.

Gate Policy

Use "advice plus gates":

• Advise the user on the next useful artifact.
• Block stage advancement when required artifacts or decisions are missing.
• Block stage advancement when any required artifact is still draft or review_requested.
• Block code generation until all required upstream artifacts are explicitly approved.
• In assisted and auto-demo, use demo-assumption or auto-continued for automatically advanced items. Do not write approved unless the user explicitly approved.
• Be direct about gaps. Do not soften missing fundamentals.
• Keep the next action small enough for a newcomer to execute.

For detailed gates, read references/stage-gates.md.

Artifact Review Protocol

After generating or updating any artifact:

1. Summarize what changed.
2. List open questions and risky assumptions.
3. Ask the user to review and approve or request changes.
4. In strict, stop. Do not continue to the next artifact in the same turn unless the user already gave explicit approval for the current artifact.
5. In assisted, continue only when the artifact is low-risk and not a critical gate; record it as auto-continued.
6. In auto-demo, continue according to dry-run or scaffold rules; record automatic assumptions as demo-assumption.

Use this fallback wording:

Please review this artifact before I continue.
Reply "approved" to proceed, or describe the changes you want.