OpenParable
Skip to content
← Back to skills

Plan Spec

Productivity
plan-spec

Plan Spec is an Agent Skill for productivity published in the majiayu000/claude-skill-registry repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Plan specification (enters plan mode)

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/majiayu000/claude-skill-registry/blob/HEAD/skills/data/plan-spec/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/plan-spec, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Plan Specification (Plan Mode)

Prerequisites

Run /fetch-issue <ALG-XX> first to fetch issue context and create branch.

Steps

  1. Enter plan mode: Call the EnterPlanMode tool to begin planning.

  2. Analyze fetched issue context from the conversation:

    • Issue title and description
    • Labels and status
    • Related specs (if any were found)
  3. Ask up to 5 clarifying questions using AskUserQuestion: Focus on:

    • Ambiguous or vague requirements
    • Missing acceptance criteria
    • Unclear scope boundaries
    • Priority of different user stories
    • Technical constraints not mentioned
  4. Explore related code if needed:

    • If related specs were found, read them for patterns
    • Search codebase for relevant existing implementations
    • Understand the domain context
  5. Propose spec structure in the plan file: Write to the plan file (NOT spec.md yet) with:

    • Summary: 2-3 sentences from issue description
    • User Scenarios & Testing:
      • Multiple user stories with priorities (P1, P2, P3)
      • Each with "Why this priority" explanation
      • Acceptance scenarios in Given/When/Then format
    • Edge Cases: Explicit list of edge cases
    • Functional Requirements: FR-001, FR-002, etc.
    • Dependencies: Links to related specs (e.g., @specs/alg-14-discover-chat)
    • Out of Scope: Explicit boundaries
  6. Exit plan mode: Call ExitPlanMode to get user approval of the proposed spec structure.

  7. After approval, write the spec file:

    • Get branch info: git rev-parse --abbrev-ref HEAD

    • Extract issue number from branch name (e.g., alg-27-* -> 27)

    • Write specs/alg-{NUM}-*/spec.md with the approved structure

    • Include header:

      # Feature Specification: {Title}
      
      **Feature Branch**: `{branch-name}`
      **Created**: {ISO date}
      **Status**: Draft
      **Linear Issue**: [ALG-{NUM}](https://linear.app/algojuke/issue/ALG-{NUM})
      **Input**: {Original issue description}
      
  8. Commit the spec:

    git add specs/alg-{NUM}-*/spec.md
    git commit -m "spec: ALG-{NUM} - initial specification"
    

Spec Template Reference

Follow the structure from existing specs like specs/alg-14-discover-chat/spec.md:

  • User Scenarios with priorities and acceptance scenarios
  • Functional Requirements numbered FR-001, FR-002
  • Clear scope boundaries
  • Clarifications section for Q&A