Create Release
Create a new software release with planning, manifest, and execution schedule.
Get the complete skill folder, including its scripts and reference files.
This page is available to readers but is excluded from the public index, because it does not yet meet the evaluation standard.
When to use this skill
Use Create Release when an AI agent needs a reusable SKILL.md workflow for this job: Create a new software release with planning, manifest, and execution schedule.
When not to use it
Skip Create Release when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.
How to install
Where will you use it?
mkdir -p ~/.claude/skills/create-release # Save SKILL.md to ~/.claude/skills/create-release/SKILL.md
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/create-release/SKILL.md. For a shared project, commit the folder at .claude/skills/create-release/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
Full install guide for Claude, Cursor, and Codex →
Try a starter prompt
After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.
Use the Create Release skill for this task: Use Create Release when this documented workflow matches the task. Confirm any required inputs or files before making changes.
What supports this recommendation?
66/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 67/100
- Practical detail
- 68/100
- Source evidence
- 56/100
- Source signals
- 72/100
Model compatibility evidence
- claudeuntested
No model-specific signal or recorded compatibility test was found.
- chatgptuntested
No model-specific signal or recorded compatibility test was found.
- geminiuntested
No model-specific signal or recorded compatibility test was found.
- copilotuntested
No model-specific signal or recorded compatibility test was found.
- llamauntested
No model-specific signal or recorded compatibility test was found.
- perplexityuntested
No model-specific signal or recorded compatibility test was found.
- mistraluntested
No model-specific signal or recorded compatibility test was found.
- grokuntested
No model-specific signal or recorded compatibility test was found.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
What this skill does
# Create New Release
Orchestrates multiple Feature Units into a cohesive release. Implements the Release workflow from `foundation/development/release_workflow.md`.
## When to Use
**Explicit Command:** Use when you know exactly what you want: start a new release, plan multi-FU work with dependency resolution, generate execution schedules with parallelization, orchestrate FU creation/execution in dependency order, run cross-FU integration tests.
**Automatic Detection:** This workflow can also be triggered automatically via `.cursor/rules/release_detection.md` when you mention release-related patterns in natural language (e.g., "new release", "release v1.1.0"). Both paths execute the same workflow.
This is a foundation command. If installed, it will be available in `.cursor/commands/` via symlink.
## Prerequisites
- Release ID chosen (format: `vX.Y.Z`, e.g., `v1.0.0`) - Release scope roughly defined (what's in, what's out) - FU IDs for included work identified (or to be created)
## Command Execution
### Step 1: Load Documentation
Load required documents: - `foundation/development/release_workflow.md` (primary workflow) - `docs/feature_units/standards/creating_feature_units.md` (FU creation) - `docs/feature_units/standards/execution_instructions.md` (FU execution) - `docs/feature_units/completed/` and `docs/feature_units/in_progress/` (for Feature Unit specs)
### Step 2: Checkpoint 0 — Release Planning
Check if Release plan exists:
- Look for `docs/releases/in_progress/{release_id}/release_plan.md` - Look for `docs/releases/in_progress/{release_id}/manifest.yaml`
**If Release plan exists:** Load and validate. If complete → proceed to Step 3. If incomplete → prompt user to complete.
**If Release plan does NOT exist:** Prompt user interactively for Release details:
1. **Release name and version** (e.g., "MVP", "v1.0.0") 2. **Release goal** (1-2 sentence summary of what this ships) 3. **Target ship date** (date or "when ready") 4. **Priority** (P0 critical / P1 high / P2 normal) 5. **Included Feature Units** (list of FU IDs, e.g., "FU-100, FU-101, FU-102") 6. **Excluded scope** (what's explicitly NOT in this release) 7. **Release-level acceptance criteria:** - Product acceptance (core workflows, empty/error states) - Technical acceptance (test coverage, performance, integrity) - Business acceptance (metrics, KPIs) 8. **Cross-FU integration test requirements** (flows that span multiple FUs) 9. **Deployment strategy** (staging_first / canary / full_rollout) 10. **Rollback plan** (how to revert if issues found) 11. **Post-release monitoring plan** (key metrics, alerts)
**After user input:** Generate complete Release plan (`release_plan.md`), create manifest YAML (`manifest.yaml`), create integration test spec (`integration_tests.md`), create status tracker (`status.md`), save all to `docs/releases/in_progress/{release_id}/`.
**After saving the release plan**, offer the publish-plan prompt once:
``` Release plan saved to docs/releases/in_progress/{release_id}/release_plan.md.
Would you like to share this as a GitHub Discussion for pre-execution input? Run /publish-plan docs/releases/in_progress/{release_id}/release_plan.md to generate a public-facing post. ```
Do not wait for a response before proceeding to Step 3.
### Step 3: Dependency Analysis and Schedule Generation
Analyze dependencies:
1. **Load all FU manifests** for FUs in Release 2. **Extract dependencies** from each FU's `dependencies.requires` field 3. **Build dependency graph**: FU → [list of required FUs] 4. **Detect cycles:** If cycle found → REJECT with error message. List cycle: "FU-A → FU-B → FU-C → FU-A" 5. **Validate dependencies:** If any required FU is ⏳ Not Started and not in this Release → REJECT. If any required FU is 🔨 Partial → WARN but allow with user confirmation. If any required FU is ✅ Complete → proceed.
Generate execution schedule:
1. **Perform topological sort** of FU dependency graph 2. **Group into batches**: - Batch 0: FUs with no dependencies - Batch 1: FUs that depend only on Batch 0 - Batch 2: FUs that depend only on Batch 0 or 1 - ... continue until all FUs assigned to batches 3. **Identify parallelization opportunities**: - Within each batch, FUs can execute in parallel 4. **Estimate timeline**: - Sum FU effort estimates per batch - Account for parallelization (divide by number of parallel agents if applicable) 5. **Save execution schedule** to `execution_schedule.md`
Pre-Mortem Analysis:
1. Identify top 3-5 most likely failure modes for this Release 2. For each failure mode, specify: - Early warning signals (metrics, test failures, timeline slips) - Mitigating FUs or actions - Rollback plan 3. Present pre-mortem to user and ask: - "Do these failure modes match your concerns? (yes/no)" - "What other failure modes should we plan for?" 4. Incorporate feedback and add "Pre-Mortem" section to Release plan
WIP and Parallelization Limits:
1. Encode limits in `manifest.yaml`: - `max_parallel_fus: <number>` (default: 3) - `max_high_risk_in_parallel: <number>` (default: 1) 2. Present limits to user: "Proposed limits: max_parallel_fus=3, max_high_risk_in_parallel=1. Approve? (yes/modify)"
Machine-Checkable Exit Criteria:
1. For each Release acceptance criterion, define: - Concrete test suite or script that validates it - Single metric or query that proves it 2. Add these to `integration_tests.md` with explicit pass/fail conditions 3. Present to user: "Each acceptance criterion now has a machine-checkable test. Review? (yes/modify)"
Present schedule to user: Display batch breakdown, show which FUs run in parallel, show estimated timeline, show WIP limits and pre-mortem failure modes. STOP and prompt: "Approve execution schedule? (yes/no/modify)"
**If user approves:**
- Initialize `status.md` with "Decision Log" section (empty initially) - Update Release status to `in_progress` - Proceed to Step 4
**If user requests modifications:**
- Adjust schedule based on user input - Re-present for approval
---
### Step 4: Execute FU Batches (Autonomous)
Before starting execution, prompt user for execution strategy: - Run `node scripts/release_orchestrator.js <release_id>` - Orchestrator will prompt: "How would you like to execute this release build? 1. Single-agent (sequential execution) 2. Multi-agent (parallel execution)" - If single-agent selected, orchestrator recommends model based on release complexity - Selected strategy saved to `manifest.yaml`
For each batch in execution schedule (in order):
**Batch Execution Loop:**
1. **Start all FUs in batch:**
- For each FU in batch: - Check if FU spec exists - If not, run `Create New Feature Unit` command (Checkpoint 0) - If UI FU and no prototype, run `Create Prototype` command - If UI FU and prototype not approved, run Checkpoint 1 (Prototype Review) - Run `Run Feature Workflow` command to implement FU - Run `Final Review` command (Checkpoint 2) for FU approval - If multiple FUs in batch, suggest running in parallel (separate agent sessions or worktrees)
2. **Wait for all FUs in batch to complete**
3. **Run cross-FU integration tests:**
- Execute integration test suite from `integration_tests.md` - Test flows that span multiple FUs in this batch - If tests fail: STOP and report failures to user. User decides: fix and retry, skip FU, or abort Release - If tests pass, proceed
4. **Update Release status:** - Mark batch as `completed` in `status.md` - Update progress percentage: `(completed_batches / total_batches) * 100` - If any decisions were made during batch execution (scope changes, FU deferrals, etc.), append to Decision Log in `status.md` with timestamp
**After all batches complete:**
- Mark all FUs as `completed` in status tracker - Proceed to Step 5
---
### Step 5: Checkpoint 1 — Mid-Release Review (Optional)
Check if mid-release checkpoint is configured: Look for `checkpoint_1_after_batch` in `manifest.yaml`. If not configured, skip to Step 6.
If configured and batch threshold reached, present mid-release status:
- "Mid-release checkpoint reached" - "FUs completed: X/Y" - "Integration tests: [pass/fail summary]" - "Current batch: N" - "Remaining batches: [list]"
**STOP and prompt user:**
- "Continue to remaining FUs? (yes/no/pause)"
**If user responds:**
- **yes** → continue to remaining batches - **no** → halt execution, mark Release as `paused` - **pause** → halt execution, user can resume later
---
### Step 6: Cross-Release Integration Testing
Run full integration test suite:
1. **Execute all tests** from `integration_tests.md` 2. **Run end-to-end user flows** that span multiple FUs 3. **Verify no regressions** in existing functionality 4. **Run performance benchmarks** (if specified in acceptance criteria) 5. **Verify graph integrity** (0 orphans, 0 cycles if applicable)
Check Release-level acceptance criteria:
- Product acceptance: Core workflows functional? - Technical acceptance: Test coverage met? Performance targets hit? - Business acceptance: Metrics instrumented? Analytics ready?
Generate integration test report:
- Save to `integration_test_report.md` - Include: - Pass/fail summary - Performance metrics - Regression test results - Issues found (if any)
**If tests fail:** STOP and report failures to user. User decides: fix issues and re-test, or abort Release.
**If all tests pass:** Proceed to Step 7.
### Step 7: Checkpoint 2 — Pre-Release Sign-Off
Present Release summary:
- FUs completed: X/Y (with list) - Integration tests: [pass/fail summary with link to report] - Acceptance criteria: [checklist with ✅ / ❌ status] - Release plan: [link] - Integration test report: [link]
**STOP and prompt user:**
- "Release {release_id} ready for deployment." - "All FUs complete: [list with status]" - "Integration tests passed: [summary]" - "Acceptance criteria met: [checklist]" - "Approve for deployment? (yes/no)" - "Any final changes needed? (list or 'none')"
**If user requests changes:**
- Apply changes - Re-run affected tests - Update status - Repeat Checkpoint 2 until approved
**If user approves:**
- Update Release status to `ready_for_deployment` - Proceed to Step 8
---
### Step 8: Deployment
Execute deployment plan:
1. **Follow deployment strategy** from Release plan: - **staging_first**: Deploy to staging, run smoke tests, then production - **canary**: Deploy to small % of users, monitor, then full rollout - **full_rollout**: Deploy to all users at once 2. **Run deployment steps:** - Build production bundle - Run database migrations (if any) - Deploy backend services - Deploy frontend assets - Run health checks - Run smoke tests 3. **Verify deployment success:** - Health checks pass? - Smoke tests pass? - Key metrics normal?
**If deployment fails:** STOP and report failure, execute rollback plan, user investigates and fixes.
**If deployment succeeds:** Update Release status to `deployed`, record deployment timestamp, proceed to Step 9.
### Step 9: Post-Release Monitoring Setup
Setup monitoring:
1. **Verify metrics instrumentation:** - Check that key metrics from acceptance criteria are being collected - Verify dashboards are accessible 2. **Setup alerts:** - Configure alerts for critical metrics (error rates, latency, etc.) 3. **Document monitoring links:** - Add links to dashboards, alerts to Release status doc
Mark Release as completed:
- Update status to `completed` - Move Release files from `in_progress/` to `completed/`: ```bash mv docs/releases/in_progress/{release_id} docs/releases/completed/{release_id} ```
Present completion summary:
- "Release {release_id} deployed and complete!" - "Deployed at: {timestamp}" - "Monitoring: {dashboard_links}" - "FUs shipped: [list]"
## Example Interaction
``` User: Create release v1.0.0 for MVP
Agent: Loading Release workflow documentation...
Agent: No existing Release plan found for v1.0.0. Starting interactive Release planning (Checkpoint 0).
Agent: What is the Release name and version? User: MVP, v1.0.0
Agent: What is the Release goal? (1-2 sentence summary) User: Ship deterministic Truth Layer with ingestion, extraction, entity resolution, timeline, and MCP access for AI tools. Support multi-user teams.
Agent: What is the target ship date? User: 2025-03-01
Agent: What is the priority? User: P0 critical
Agent: Which Feature Units should be included? (list FU IDs) User: FU-100, FU-101, FU-102, FU-103, FU-105, FU-300, FU-700, FU-701
Agent: [loads the matching Feature Unit specs from `docs/feature_units/`]
Agent: What scope is explicitly excluded from this release? User: Semantic search, Plaid integration, X/Instagram integrations (all post-MVP)
Agent: What are the Release-level acceptance criteria? (product, technical, business) User: [provides release-specific criteria]
Agent: What cross-FU integration tests are required? User: Full user flow: upload → extraction → entity resolution → event generation → timeline display → AI query via MCP
Agent: What is the deployment strategy? User: staging_first
Agent: What is the rollback plan? User: Revert to previous release tag, restore DB snapshot if needed
Agent: What monitoring plan should be setup post-release? User: Monitor upload success rate, P95 latency, DAU, orphan node count
Agent: Generating Release plan, manifest, and integration test spec... Agent: Analyzing FU dependencies... Agent: Dependency graph: FU-100 → [] FU-101 → [FU-100] FU-102 → [FU-100] FU-103 → [FU-101, FU-102] FU-105 → [FU-103] FU-300 → [] FU-700 → [] FU-701 → [FU-700]
Agent: Generating execution schedule... Agent: Execution schedule: Batch 0: FU-100, FU-300, FU-700 (can run in parallel) Batch 1: FU-101, FU-102 (can run in parallel, depend on FU-100) Batch 2: FU-103 (depends on FU-101, FU-102) Batch 3: FU-105, FU-701 (can run in parallel, FU-105 depends on FU-103, FU-701 depends on FU-700)
Agent: Estimated timeline: 11-14 days (with parallelization across 3 agents)
Agent: Approve execution schedule? (yes/no/modify) User: yes
Agent: Starting batch execution... Agent: Batch 0: Starting FU-100, FU-300, FU-700 in parallel... [FU execution proceeds autonomously] Agent: Batch 0 complete. Running cross-FU integration tests... Agent: Integration tests passed. Agent: Batch 1: Starting FU-101, FU-102 in parallel... [continues through all batches]
Agent: All batches complete. Running full integration test suite... Agent: All integration tests passed. Agent: Release v1.0.0 ready for deployment. Agent: All FUs complete: FU-100 ✅, FU-101 ✅, FU-102 ✅, FU-103 ✅, FU-105 ✅, FU-300 ✅, FU-700 ✅, FU-701 ✅ Agent: Integration tests passed: 12/12 Agent: Acceptance criteria met: ✅ Product, ✅ Technical, ✅ Business Agent: Approve for deployment? (yes/no) User: yes
Agent: Deploying to staging... Agent: Staging smoke tests passed. Agent: Deploying to production... Agent: Production health checks passed. Agent: Release v1.0.0 deployed and complete! Agent: Monitoring: [dashboard links] ```
## Agent Instructions
### Load Order
1. `foundation/development/release_workflow.md` (primary) 2. `docs/feature_units/standards/creating_feature_units.md` (for FU creation) 3. `docs/feature_units/standards/execution_instructions.md` (for FU execution) 4. `docs/feature_units/completed/` and `docs/feature_units/in_progress/` (for Feature Unit specs)
### Constraints
- Do NOT proceed past Checkpoint 0 without complete Release plan - Always validate FU dependencies before generating schedule - REJECT if circular dependencies detected - Always run cross-FU integration tests after each batch - Always get user approval at Checkpoints 0, 1 (if configured), 2 - Do NOT deploy without passing integration tests and acceptance criteria
### Forbidden Patterns
- Starting FUs out of dependency order - Skipping integration tests - Proceeding without user approval at checkpoints - Deploying with failing tests or unmet acceptance criteria
Intended uses
- Use Create Release when this documented workflow matches the task.
Implementation notes
- Review the source instructions and adapt inputs before running the workflow.
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.