Skip to content

About

22 composable, auto-triggering skills engineering documentation skills covering the complete software lifecycle: spec, feasibility, architecture, design, API, database, ADR, security, deployment, operations, and incident review

Topics

Resources

Contributing

Security policy

Stars

6 stars

Watchers

1 watching

Forks

Repository files navigation

Engineering Docs

22 composable, auto-triggering skills that turn your coding agent into a principal engineer - from raw idea to production-ready documentation.

npm version GitHub stars Security: A - Skills Directory Listed on ClaudePluginHub Listed on mcpservers.org


Why Engineering Docs?

Your coding agent is powerful, but it doesn't know your project's architecture, your users, or your constraints. Engineering Docs gives it principal-level documentation skills — so it can:

  • Turn raw ideas into complete blueprints — business concept → technical spec → architecture → deployment plan
  • Ask the right questions — tool-call interviews with 2-3 targeted questions per skill (no repeated questions)
  • Generate production-ready documents — ISO/IEC/IEEE 29148, C4 Model, STRIDE, Google SRE standards
  • Work across 14+ agents — Claude Code, Copilot, Cursor, Gemini CLI, Goose, Pi, and more

How It Works

Engineering Docs Plugin Workflow

The plugin works through a structured workflow:

  1. User gives idea → Orchestrator skill activates automatically
  2. Mode detection → Greenfield (new) vs Brownfield (existing)
  3. Interview phase → Tool-call questions with context loading
  4. Document generation → Sequential generation with 22 specialized skills
  5. Consistency checks → Cross-document verification
  6. Master index → Complete blueprint ready for implementation

Quickstart

npx engineering-docs

Or install for your specific agent:

Agent Install Command
Claude Code /plugin marketplace add fattain-naime/engineering-docs
/plugin install engineering-docs@engineering-docs
Gemini CLI gemini extensions install https://github.com/fattain-naime/engineering-docs
Cursor npx engineering-docs --cursor
Goose npx engineering-docs --goose
Pi npx engineering-docs --pi
OpenCode npx engineering-docs --opencode
Kilo Code npx engineering-docs --kilo
Roo Code npx engineering-docs --roo
Cline npx engineering-docs --cline
Kimi Code /plugins install https://github.com/fattain-naime/engineering-docs
Codex npx engineering-docs --codex
Copilot CLI npx engineering-docs --copilot
Factory Droid npx engineering-docs --factory

See Installation for detailed instructions.


How It Works

graph LR
    A[Your Idea] --> B[Orchestrator]
    B --> C[Interview]
    C --> D[Business Concept]
    D --> E[Project Plan]
    E --> F[Technical Spec]
    F --> G[System Architecture]
    G --> H[API Design]
    H --> I[Implementation Plan]
    I --> J[Test Strategy]
    J --> K[Deployment Plan]
    K --> L[Master Index]
Loading
  1. Give it your idea — "I want to build X"
  2. Answer 2-3 questions per skill — via tool calls, not inline chat
  3. Review each document — approve or request changes
  4. Get your blueprint — complete, cross-consistent documentation set

Smart features:

  • Context loading — reads prior documents before asking questions (never repeats)
  • Tool-call interviews — clean input capture, no conversation pollution
  • Right-sizing — skips documents that don't apply to your project
  • Cross-document consistency — verifies entity names, roles, decisions match

What's Inside

Skills Library (22 Skills)

Discovery & Planning

Skill What It Produces
using-engineering-docs Orchestrator — routes to all other skills automatically
business-concept Problem, users, value proposition, monetization, constraints
project-plan Scope, milestones, RACI, timeline, work breakdown
user-personas-behavior User personas, JTBD, success metrics, analytics plan

Specification & Feasibility

Skill What It Produces
technical-specification SRS/TSD with EARS syntax, traceability matrix
technical-feasibility-study Go/no-go recommendation with evidence

Architecture & Design

Skill What It Produces
system-architecture-document C4 diagrams, 4+1 views, tech stack, NFRs
architecture-decision-record Immutable ADR log (MADR format)
database-design-document ERD, schema, indexing, migration plan
api-design-document REST/OpenAPI 3.1 contract, RFC 7807 errors
admin-access-control-specification RBAC matrix, audit logging, break-glass
technical-blueprint Google/Stripe-quality TDD per feature
ux-flow-specification User journeys, screen flows, UI states
design-system-specification Design tokens, components, accessibility

Quality & Risk

Skill What It Produces
security-threat-model STRIDE analysis, attack surface, mitigations
test-strategy-document Testing pyramid, CI gates, coverage targets
implementation-plan Dependency-ordered build sequence, phase gates

Delivery & Operations

Skill What It Produces
deployment-plan Release strategy, go/no-go gate, rollback
slo-error-budget-document SLI/SLO targets, burn-rate alerts
technical-runbook On-call operations manual (Google SRE)
disaster-recovery-plan RTO/RPO, backup strategy, failover
incident-postmortem Blameless RCA with Five Whys

Custom Agents (4 Agents)

Agent Purpose
documentation-generator Generate comprehensive documentation for software projects
architecture-reviewer Review system architecture for scalability, security, and maintainability
api-designer Design RESTful APIs following best practices
test-strategist Create comprehensive test strategies for software projects

Utility Scripts

Script Purpose
generate-dependency-graph.js Mermaid dependency visualization
validate-documents.js Document validation
calculate-error-budget.js SLO error budget calculator
generate-test-cases.js Test case generator from specs
generate-ddl.js SQL DDL generator from schema
check-consistency.js Cross-document consistency checker

MCP Integration

.mcp.json          # MCP server configuration
scripts/validate.js    # Validation server (validate_document_set, check_consistency, generate_index)

Hooks

hooks/hooks.json          # SessionStart hook configuration
hooks/check-progress.js   # Check for in-progress documentation
hooks/run-hook.cmd        # Windows compatibility

Eval Framework

evals/evals.json           # Test cases for orchestrator and key skills
evals/README.md            # How to run evals
evals/test-prompts/        # Sample test prompts

Plugin Structure (Claude Compatible)

engineering-docs/
├── .claude-plugin/
│   ├── plugin.json        # Plugin manifest
│   └── marketplace.json   # Marketplace manifest
├── .kimi-plugin/
│   └── plugin.json        # Kimi Code plugin manifest
├── gemini-extension.json  # Gemini CLI extension manifest
├── GEMINI.md              # Gemini CLI extension context file
├── skills/                # 22 skills (SKILL.md files)
├── agents/                # 4 custom agents
├── hooks/                 # Event handlers
├── .mcp.json              # MCP server configuration
├── scripts/               # Installer, validator, test runner, and utility scripts
├── evals/                 # Test framework
└── integrations/          # Other agent platform configs
    ├── agents/            # Agent instruction files (AGENTS.md, CLAUDE.md)
    └── plugins/           # Cline rules source (.clinerules/)

Claude Guidelines Compliance:

  • ✅ Components at plugin root (not inside .claude-plugin/)
  • ✅ Skills in skills/ directory with SKILL.md
  • ✅ Agents in agents/ directory with frontmatter
  • ✅ Hooks in hooks/hooks.json
  • ✅ MCP in .mcp.json
  • ✅ Kebab-case naming
  • ✅ Validation passes: claude plugin validate .

Installation

CLI Installer (Recommended)

npx engineering-docs

Automatically detects and copies the plugin to your agent's directory.

Per-Agent Installation

Claude Code

/plugin marketplace add fattain-naime/engineering-docs
/plugin install engineering-docs@engineering-docs

Gemini CLI

gemini extensions install https://github.com/fattain-naime/engineering-docs

Or with the CLI installer (installs to ~/.gemini/extensions/engineering-docs/):

npx engineering-docs --gemini

The extension layout follows the Gemini CLI extension spec: gemini-extension.json + GEMINI.md context file + skills/.

Cursor / Windsurf

npx engineering-docs --cursor

Writes each skill to .cursor/rules/engineering-docs-*.mdc with Cursor's documented frontmatter (description, globs, alwaysApply).

Goose

npx engineering-docs --goose

Installs skills to ~/.agents/skills/ (the shared Agent Skills directory Goose reads).

Pi

npx engineering-docs --pi

Safe-writes AGENTS.md to ~/.pi/agent/AGENTS.md.

OpenCode

npx engineering-docs --opencode

Installs skills to .opencode/skills/.

Kilo Code

npx engineering-docs --kilo

Safe-writes AGENTS.md to ~/.config/kilo/AGENTS.md.

Codex

npx engineering-docs --codex

Safe-writes AGENTS.md to ~/.codex/AGENTS.md.

Copilot CLI

npx engineering-docs --copilot

Installs to ~/.copilot/installed-plugins/engineering-docs/ (Copilot CLI reads .claude-plugin/plugin.json).

Cline

npx engineering-docs --cline

Creates .clinerules/engineering-docs.md (rules directory) and .cline/skills/ in your project root, matching Cline's documented workspace layout.

Factory Droid

npx engineering-docs --factory

Installs skills to ~/.factory/skills/.

Roo Code

npx engineering-docs --roo

Writes ~/.roo/rules/engineering-docs.md.

Kimi Code

npx engineering-docs --kimi

Or install inside Kimi Code:

/plugins install https://github.com/fattain-naime/engineering-docs

The repo-root .kimi-plugin/plugin.json manifest follows Kimi Code's plugin spec.

Cross-Platform Scripts

# Windows (PowerShell)
pwsh scripts\setup.ps1
pwsh scripts\setup.ps1 -Target gemini
pwsh scripts\setup.ps1 -Target claude

# Linux / macOS (Bash)
chmod +x scripts/setup.sh
./scripts/setup.sh
./scripts/setup.sh --gemini
./scripts/setup.sh --claude

Supported targets: gemini, claude, local, cursor, kimi, codex, goose, pi, opencode, kilo, roo, cline, factory, copilot

Safe-Write Behavior

All install methods use safe-write for agent instruction files:

  • AGENTS.md — Created only if it doesn't exist
  • CLAUDE.md — Created only if it doesn't exist
  • GEMINI.md — Created only if it doesn't exist

Your customizations are always preserved.


Multi-Agent Compatibility

Platform Manifest / Layout Installation Path
Claude Code .claude-plugin/plugin.json ~/.claude/plugins/engineering-docs/
Gemini CLI gemini-extension.json + GEMINI.md + skills/ ~/.gemini/extensions/engineering-docs/
Cursor / Windsurf .cursor/rules/*.mdc (frontmatter: description, globs, alwaysApply) ./.cursor/rules/engineering-docs-*.mdc
Kimi Code .kimi-plugin/plugin.json ~/.kimi-code/plugins/engineering-docs/
Codex AGENTS.md instructions file ~/.codex/AGENTS.md
OpenCode Agent Skills (SKILL.md per skill) ./.opencode/skills/
Goose Agent Skills (SKILL.md per skill) ~/.agents/skills/
Pi AGENTS.md instructions file ~/.pi/agent/AGENTS.md
Kilo Code AGENTS.md instructions file ~/.config/kilo/AGENTS.md
Roo Code Markdown rule file ~/.roo/rules/engineering-docs.md
Cline .clinerules/*.md + .cline/skills/ ./.clinerules/engineering-docs.md
Factory Droid Agent Skills (SKILL.md per skill) ~/.factory/skills/
Copilot CLI .claude-plugin/plugin.json ~/.copilot/installed-plugins/engineering-docs/

Testing

# Run plugin validation
claude plugin validate .

# Run skill tests
npm test

# Test MCP server
node scripts/validate.js

Testing Claude Code plugins

Validate manifests and run behavioral evals with the official Claude Code CLI:

claude plugin validate .
claude plugin eval init --bare first-case
claude plugin eval . --trust-plugin

See docs/claude-plugin-testing.md for the full command surface, the Plugin Developer Toolkit, and CI. This repository gates pull requests on validate with .github/workflows/claude-plugin-ci.yml; copy that file into your own repo's .github/workflows/ to get the same gate. The eval step only runs on manual dispatch and needs an ANTHROPIC_API_KEY secret (or gateway variables).


Philosophy

  • Systemic over Ad-hoc — Rigorous, reproducible processes yield safer and cleaner software
  • Traceability — Every requirement links to a business goal and a test case
  • Visual-First — Complex architectures mapped with Git-trackable Mermaid diagrams
  • Operational Safety — No feature is complete without deployment runsheet, monitoring, rollback
  • Blameless Learning — Production failures are data points for system hardening

Contributing

We welcome community skills! Please review CONTRIBUTING.md for guidelines.


Community


Author


License

MIT. See LICENSE.

About

22 composable, auto-triggering skills engineering documentation skills covering the complete software lifecycle: spec, feasibility, architecture, design, API, database, ADR, security, deployment, operations, and incident review

Topics

Resources

Contributing

Security policy

Stars

6 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages