project-blueprint

Project Blueprint 🏗️

> One command to make any project AI-agent-ready.

> 一键为新项目建立完整 AI 编程规范体系。

Topics ·

[中文文档](README_CN.md)

---

What is this?

Project Blueprint is a reusable AI agent skill that transforms any new project into an AI-ready codebase in one sentence. It's not a static template — it's an autonomous discovery engine: scan your project files, intelligently classify dependencies, and dynamically assemble a customized AGENTS.md, documentation skeleton, CI/CD pipeline, and testing policy from a 95-entry component knowledge base.

Just say: "Initialize this project's development standards" and the agent does the rest.

Quick Install

# Global (GitHub)
npx skills add shuguang1994/project-blueprint

# China (Gitee mirror, no proxy needed)
npx skills add https://gitee.com/shuguang1994/project-blueprint.git

# Update later
npx skills update project-blueprint

DeepSeek Harness (dsh) plugin:

dsh plugin --profile web add 'github:shuguang1994/project-blueprint'

Supported agents: Claude Code, Cursor, GitHub Copilot, Codex, Windsurf, Trae, OpenCode, DeepSeek Harness, and 28+ more.

Why

AGENTS.md is now an industry standard in 2026 — used by 60,000+ open-source repos, co-promoted by OpenAI, Google, Anthropic, and Microsoft. 76% of developers use AI coding assistants (Stack Overflow 2025), but without AGENTS.md, AI agents are like "new hires with no onboarding" — producing inconsistent code styles, broken architecture, and failing CI.

Industry data: Anthropic benchmarks show AGENTS.md reduces wrong-pattern rewrites by 40-60%. But writing a quality AGENTS.md by hand takes half a day to a full day — repeated for every new project.

Project Blueprint's approach: No preset templates. Autonomous scanning → intelligent classification → dynamic assembly. The AGENTS.md you get reflects your project's actual tech stack. And it's the only tool that generates AGENTS.md + docs skeleton + CI pipeline + testing policy + Git conventions — all from one sentence.

Core Capabilities

| Capability | Description |

|------------|-------------|

| Autonomous File Discovery | Scan and classify 30+ file patterns — no preset file checklist |

| Project Structure Detection | Auto-identify monorepo, 2/3-tier frontend-backend, or single project |

| Monorepo Nested AGENTS.md | Root AGENTS.md (global constraints + sub-project index) + per-package AGENTS.md (closest-file-wins) when ≥2 build/manifest files |

| Intelligent Dep Classification | 3-tier: knowledge base exact match → 29 heuristic patterns → web search |

| Business Type Inference | 2-tier heuristic (structure + config features), 12 business types |

| Dynamic AGENTS.md | Assembled from a 95-entry component knowledge base, not a template |

| Module Table Generation | Reads actual source dirs, infers responsibilities via file patterns, web search fallback |

| Documentation System | A/B/C/D/E 5-tier classification, generated per business type |

| Testing Policy | Phase-appropriate layered strategy, not forced example files |

| Multi-IDE Support | Auto-generates CLAUDE.md, .cursor/rules, copilot-instructions, and more |

| Vendor Private Enhancement Layer | Beyond breadcrumbs: Cursor .mdc glob activation, Claude Code hooks/subagents skeleton, Copilot instructions layering |

| Incremental Mode | Only fills gaps on existing projects, never overwrites |

| MCP Tool Recommendation | Recommends MCP tool list + combinations from detected stack, generates docs/B/B-05-MCP工具清单.md with install commands (MD only, minimal intrusion) |

| Self-Evolving | Generated AGENTS.md includes auto-maintenance rules — updates module table, tech stack, and decisions as the project grows |

| Progressive Step Loading | SKILL.md slimmed to a ≤200-line index; Step details load on demand from references/step-*.md |

| Real Coding Conventions | Writes base coding conventions at init (naming/structure/error handling/logging/security/performance 6 categories), B-01 as real 8-chapter doc, not a placeholder |

| AI Mistake Prevention | Built-in 7-category 27-item AI common-mistakes KB, injected into core rules at init, iterated via BUG feedback loop |

| Constitution & Gate Growth | Writes meta-rules + a 6-step growth loop into AGENTS.md, so the project's AI grows domain gates from the constitution while it works |

| Gate Registry & Unified Entry | scripts/gates.json as single source of truth + verify.* unified entry; the CI gate job is inlined (no "remember to append"), and every job self-verifies its runtime (command -v + version print) so a missing runtime fails on line one |

| Red-Line Authority Table + Two-Way Constitutional Review | Stable IDs (RL-NN, append-only) + docs/B/B-00-红线与门禁映射.md as the single source reference; check-constitution rules A–E review both directions — zombie gates and (rule E) red lines that have no gate; when the table is absent it degrades and states the uncovered risk instead of silently going green |

| Doc Contract & Validation | Doc state headers / numbering / index contract + docs-check script (error blocks, warning does not) |

| AI Work Protocol | 7-step task lifecycle + evidence standards + DoD + defect retrospective template |

| Spec-Driven Development (6 phases) | specify → plan → tasks → checklist → implement → verify; a spec checklist can register directly as a gate (source: spec#) |

| Spec-Code Drift Gate | Seed gate checks deps ↔ AGENTS.md tech-stack row, module table ↔ actual dirs, gate validity, and test framework ↔ CI test step (drift-check.*); falls back to top-level dirs when no source root exists and prints an applicability ruling (reason/risk/verdict) instead of skipping silently |

What It Generates

| Output | Description |

|--------|-------------|

| AGENTS.md | Project conventions (governed by architecture princ