Setup Specs Workflow

Dev Pairing Workflow Bootstrap

Bootstrap a docs-first Dev Pairing (AI + human dev) workflow and plan bookkeeping structure for projects that do not yet have one.

Read this skill folder's README.md only when the user asks for rationale or you need to explain the workflow model. The executable bootstrap rules are in this SKILL.md and the bundled blueprint/ files.

Resource Path Rules

This skill has two different file roots. Keep them separate:

• Skill resources: files bundled with this skill, resolved relative to this SKILL.md file. This includes

README.md, UPGRADING.md, and everything under this skill's blueprint/ directory.

• Target project files: files in the repository being bootstrapped or upgraded, under the chosen planning root such

as .specs/, docs/, project-specs/, .agents/specs/, or ai/.

When these instructions say to read or copy from blueprint/..., read from this skill folder's bundled blueprint/ directory, not from the target project. When these instructions say /..., read or write the target project file.

When To Use

Use this skill when asked to add planning conventions, ADRs/decision records, PRD/product docs, plan/checkpoint workflows to a new or under-documented repo, or when asked to upgrade an existing older planning workflow to the current conventions.

When the user asks to upgrade, refresh, migrate, modernize, or bring up to date an existing project planning workflow, planning docs directory, spec workflow, or older setup-specs-workflow installation, read this skill folder's UPGRADING.md before editing. Preserve project-truth files, replace workflow-rule files from this skill folder's blueprint/ directory where instructed, and report what was replaced, merged, initialized, renamed, created with TBD, or left for human review. For upgrades, follow UPGRADING.md as the migration workflow before applying the bootstrap workflow below.

Do not use it for implementing an existing plan. Use the plan handoff or plan creator skills for that.

Goal

After bootstrapping, future coding agents should understand how to:

• read the product requirements, current business rules, and decisions before coding
• consult current business rules before changing product/domain behavior
• create and update decision records
• create and update business-rule records
• create and update scoped bug-fix records for defects that do not need roadmap plan sequencing
• create implementation plans from requirements/decisions
• implement plans phase-by-phase
• resume from the current milestone/coordination/plan/checkpoint state
• create checkpoints after phases
• coordinate parallel sessions, branches, or worktrees without relying on chat history
• add dated implementation updates when code changes make docs stale
• keep canonical automated checks and manual QA coverage visible to future agents
• mark release-visible changelog impact in plans, checkpoints, and bug-fix records
• validate workflow structure with validate-specs-workflow when users ask to audit or check .specs
• stop implementation loops when checks repeatedly fail, verification cannot run, constraints conflict, or scope expands
• fetch current library/tool documentation with Context7 before answering library-specific questions or implementing

against unfamiliar/current APIs

Required Output Contract

This skill must create or update a concrete workflow, not merely describe one. Before finishing, verify that every required file exists under the chosen planning root and that /GUIDE.md is usable as a standalone operating manual an agent can follow directly.

Required generated or adapted files:

• /PRODUCT.md
• /MILESTONES.md
• /BUG_FIXES.md
• /BUSINESS_RULES.md
• /COORDINATION.md
• /GUIDE.md
• /CHECKS.md
• /MANUAL_QA.md
• /ENV_VARS.md
• /SECURITY.md
• /setup/local-development.md
• /setup/production-hosting-and-deployment.md
• /templates/DECISION.md
• /templates/MILESTONE.md
• /templates/BUG_FIX.md
• /templates/BUSINESS_RULE.md
• /templates/PLAN.md
• /templates/PLAN_CHECKPOINT.md

Recommended edited file:

• When a project agent guide exists (AGENTS.md, CLAUDE.md, .cursor/rules, or equivalent), it should include the

adapted workflow instructions from Project Agent Guide Section below, including BUSINESS_RULES.md for current domain rules and COORDINATION.md as a required active-work board. If no agent guide exists, create one unless the user explicitly wants the workflow to live only in the planning root. In all cases, do not rely on the agent guide for workflow correctness; GUIDE.md must carry the complete rules.

DESIGN.md is optional. Create it only when the project already has design guidance, the user asks for design guidance, or UI work calls for the create-design-guidelines skill.

Target Structure

Create or adapt this structure under the project's planning root.

Default planning root: .specs/.

If the user asks for another root, such as project-specs/, .agents/specs/, or ai/, use that root consistently in all generated files, links, and agent-guide instructions. In the generated agent guide, state the chosen root near the workflow instructions so future agents know where to look.

/
  PRODUCT.md
  MILESTONES.md
  BUG_FIXES.md
  BUSINESS_RULES.md
  COORDINATION.md
  GUIDE.md
  CHECKS.md
  MANUAL_QA.md
  ENV_VARS.md
  SECURITY.md
  DESIGN.md                  # optional; generated by a design skill when needed
  templates/
    DECISION.md
    MILESTONE.md
    BUG_FIX.md
    BUSINESS_RULE.md
    PLAN.md
    PLAN_CHECKPOINT.md
  decisions/
  milestones/
  bug-fixes/
  business-rules/
  research/
  plans/
  checkpoints/
  setup/
    local-development.md
    production-hosting-and-deployment.md

Document Roles

• PRODUCT.md: master product requirements document (PRD). High-level requirements, constraints, scope, non-goals,

operating assumptions.

• MILESTONES.md: durable milestone index. Cross-milestone order, milestone status, active milestone, recommended next

plan, latest checkpoint pointer, and links to detailed milestone records in milestones/. It should not duplicate drafted-plan registries or phase maps.

• milestones/: detailed milestone records. Use these when a milestone needs its own objective, scope, phase map,

acceptance criteria, drafted plans, related business rules, decisions, or checkpoint rollups.

• BUG_FIXES.md: scoped bug-fix index. Tracks active defect records, status, priority, report/fix dates, and links to

detailed report+fix records in bug-fixes/.

• bug-fixes/: scoped bug report and fix proposal records. Use these for defects that need durable reproduction notes,

impact, evidence, root-cause notes, fix proposal, validation plan, and outcome without turning the work into a roadmap milestone plan.

• BUSINESS_RULES.md: current business-rule index. Groups durable product/domain rules by area and links to detailed

records in business-rules/.

• business-rules/: current normative product/domain rules. These state what the system must currently do. They are

different from decisions, which explain why a choice was made and what alternatives were rejected.

• COORDINATION.md: active parallel-work board. Who/what is currently working, session/branch/worktree location,

project/worktree directory, current task state, blockers, handoff links, and short-lived coordination notes. This file is allowed to be more volatile than MILESTONES.md and is maintained manually.

• GUIDE.md: centralized planning workflow guide. It replaces per-directory README files and explains naming,

lifecycles, indexes, plan/checkpoint workflows, research promotion, and setup guide conventions.

• CHECKS.md: canonical automated verification contract. Lists install, format, lint, typecheck, test, build, smoke,

preview, CI, and release checks with when to run them, expected runtime, reliability notes, and fallback behavior.

• MANUAL_QA.md: live manual QA coverage map. Describes product areas, feature workflows, roles/personas, setup data,

browser/device expectations, acceptance signals, and stale or missing coverage. Keep it current when meaningful changes affect how important flows should be manually verified.

• decisions/: architecture/product decision records. Durable, load-bearing decisions and tradeoff history.
• plans/: implementation plans written after product requirements, business rules, and decisions are clear. Plans are

divided into phases.

• checkpoints/: implementation checkpoints for plan phases. Capture what changed, checks run, surprises, and

follow-ups.

• research/: brainstorms, AI chats, spike notes, comparisons, rough thinking. Can become stale.
• setup/: local development, production hosting, deployment, self-hosting, and operational setup guides.
• ENV_VARS.md: env var catalog with purpose, default, required/optional, scope, and security notes.
• SECURITY.md: security model, threat assumptions, secret handling, reporting process, and operational hardening.
• DESIGN.md: master design guidelines. If present, follow it for UI work; if missing and UI work is requested, suggest

generating it with the create-design-guidelines skill.

• Root CHANGELOG.md: optional release communication output. It is updated by the generate-changelog skill from

planning-spec evidence using prepend-only dated blocks, not by rewriting historical entries.

• validate-specs-workflow: companion validation skill with a bundled script for checking workflow structure, links,

naming, required sections, changelog impact fields, checks, manual QA coverage, and obvious placeholders.

Bootstrap Workflow

1. Inspect the repo first:

• existing docs
• package/framework hints
• README
• existing setup/security/env files
• scripts for dev, test, build, migrations, code generation, and deployment
• hosting/deployment manifests such as Dockerfiles, Compose files, Kubernetes manifests, Terraform, serverless, PaaS

config, process managers, CI/CD workflows, or release scripts

1. Choose the planning root:

• Use the user's requested directory when provided.
• Otherwise prefer the existing planning-docs directory if one clearly exists.
• Otherwise use .specs/.

1. Preserve existing content. Do not overwrite useful docs; merge or add dated sections.
2. Create missing directories and every required file from Required Output Contract.
3. Adapt the matching files from this skill folder's bundled blueprint/ directory wherever a blueprint file exists.

The blueprint files are canonical scaffold sources to adapt, not optional inspiration. Replace placeholder paths, names, dates, and sample rows with repo-specific content or TBD.

1. Copy this skill folder's bundled blueprint/GUIDE.md to /GUIDE.md nearly verbatim. The copied guide

must remain standalone so future users can say things like "following docs/GUIDE.md, elaborate a milestone/plan for ...", even if the project has no root agent guide. Only adapt these touch points:

• planning root paths, such as .specs/
• [project name]
• links or examples that must change because the planning root is not .specs/

Do not rewrite the guide's rules, document roles, lifecycle guidance, vocabulary, or workflow sections just to match local tone. Do not create per-directory README files; GUIDE.md supersedes them.

1. Fill any required file without a one-to-one example with concise, reusable structure.
2. Seed PRODUCT.md, MILESTONES.md, BUG_FIXES.md, BUSINESS_RULES.md, COORDINATION.md, CHECKS.md,

MANUAL_QA.md, ENV_VARS.md, SECURITY.md, and the setup guides with what can be inferred; mark unknowns as TBD.

1. Scaffold setup guides by inference:

• setup/local-development.md: how a contributor gets the project running from a checkout.
• setup/production-hosting-and-deployment.md: how an operator hosts and deploys a production-like instance.
• Keep hosting guidance generic. Mention Docker, Compose, Kubernetes, serverless, PaaS, SSH servers, package

artifacts, or static hosting only when the repo actually indicates that path.

• If production deployment is not yet defined, create the guide with inferred prerequisites, open questions, and safe

TBD placeholders instead of inventing an architecture.

1. Add or update an agent guide (AGENTS.md, CLAUDE.md, .cursor/rules, or equivalent) with the workflow in **Agent

Guide Requirements** below, unless the user explicitly wants no agent guide.

1. Run formatter/checks appropriate for markdown if available.
2. Confirm in the final response that GUIDE.md is standalone, that BUG_FIXES.md, BUSINESS_RULES.md,

COORDINATION.md, CHECKS.md, and MANUAL_QA.md were created or updated, and whether an agent guide was created or updated.

Agent Guide Requirements

Add the workflow instructions in Project Agent Guide Section to the target project's agent guide when one exists or when creating one is acceptable. Treat this as a convenience entrypoint; /GUIDE.md remains the complete workflow source of truth.

• Prefer the existing project guide when present: AGENTS.md, CLAUDE.md, .cursor/rules, or equivalent.
• Merge the section into the existing guide. Preserve existing instructions, stronger local rules, headings, and tone.
• If there is no project guide, create AGENTS.md with the adapted section unless the user explicitly wants no agent

guide.

• Replace .specs/ paths with the chosen planning root when the project uses a different root.
• Keep the section concise and repo-specific. It should route agents to /GUIDE.md, not duplicate the

guide's document roles, lifecycle rules, naming conventions, status vocabulary, or templates.

• Preserve only cockpit-level requirements in the agent guide: planning root, fresh-session bootstrap order, a clear

statement that GUIDE.md is the workflow source of truth, docs-sync reminder, COORDINATION.md reminder, and local git/index rules.

Project Agent Guide Section

Use blueprint/AGENT_GUIDE.md as the source text. Adapt only the planning root, project name/context if needed, and links that must change for the target repo. Keep the project agent guide thin; detailed workflow explanations belong in /GUIDE.md.

Workflow Docs To Generate

/MILESTONES.md should include:

• status vocabulary link back to GUIDE.md
• current focus with active milestone, recommended next plan, latest checkpoint, coordination board, and business-rule

index links

• milestone index table with number, title, status, record link, and summary
• recommended execution order
• explicit note that drafted plans, phase maps, risks, acceptance criteria, and checkpoint rollups live in milestone

records

• link to GUIDE.md for workflow conventions, plan creation, templates, and resume workflow
• link to CHECKS.md and MANUAL_QA.md where recommended next work depends on verification or manual QA

/BUG_FIXES.md should include:

• bug-fix status vocabulary link back to GUIDE.md
• active bug fixes table with bug id, title, status, priority, owner, record link, and next step
• bug-fix index table with id, title, status, priority, reported date, fixed date, and record link
• explicit note that reproduction steps, diagnosis, proposed fix, validation, and outcome live in linked bug-fixes/

records

• rule to use bug-fix records for scoped defects and promote to plans when the fix becomes multi-phase,

architecture-changing, migration-heavy, cross-domain, or roadmap-visible

• links to CHECKS.md and MANUAL_QA.md for validation guidance

/BUSINESS_RULES.md should include:

• business-rule status vocabulary link back to GUIDE.md
• business-rule index grouped by product/domain area
• links to detailed records in business-rules/
• ownership or source-of-truth notes when known
• distin

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: itsjavi
• Source: itsjavi/skills
• License: MIT

Install and usage instructions live in the source repository linked above.