跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
搜索与研究

piv-plan-implementation

Creates a comprehensive, context-rich implementation plan through deep codebase analysis, a short clarifying interview, and external research. Accepts a tracker ticket (a Jira/Linear/GitHub key or URL, fetched from the tracker) or a free-form feature request. Use when you have a ticket or feature and need a one-pass-ready plan before writing any code.

coleam00 · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add coleam00/skills --skill piv-plan-implementation

技能说明


name: piv-plan-implementation description: Creates a comprehensive, context-rich implementation plan through deep codebase analysis, a short clarifying interview, and external research. Accepts a tracker ticket (a Jira/Linear/GitHub key or URL, fetched from the tracker) or a free-form feature request. Use when you have a ticket or feature and need a one-pass-ready plan before writing any code. argument-hint: "[ticket key/URL (fetched from your tracker), or a free-form feature description]"

Plan a new task

Feature: $ARGUMENTS

Resolve the input first

$ARGUMENTS is either a tracker ticket (a key like ACC-30, or a Jira / Linear / GitHub issue URL) or a free-form feature description. Tell them apart and handle each:

  • A ticket (a key such as ABC-123, or an issue URL): fetch it from the tracker before you plan (Jira via the Atlassian MCP, GitHub via gh issue view, etc.). Read its summary, acceptance criteria, and per-ticket context. Then follow its links up to the epic and the epic's linked architecture page (Confluence via the Atlassian MCP) and inherit those decisions (see "Inherit, don't re-decide" below). Never plan from the bare key; the ticket body plus its epic and architecture are the real input.
  • A free-form description: plan directly from it (greenfield or ad-hoc), asking clarifying questions as needed.

Mission

Transform a feature request into a comprehensive implementation plan through systematic codebase analysis, external research, and strategic planning.

Core Principle: We do NOT write code in this phase. Our goal is to create a context-rich implementation plan that enables one-pass implementation success for ai agents.

Key Philosophy: Context is King. The plan must contain ALL information needed for implementation - patterns, mandatory reading, documentation, validation commands - so the execution agent succeeds on the first attempt.

Inherit, don't re-decide: This is a per-ticket plan. If the ticket belongs to an epic that already has architecture decisions — a linked architecture page (e.g. a Confluence page from the plan-architecture skill, reached from the ticket's epic), an ## Architecture / ## Engineering section on the epic, or a local architecture.md / engineering-plan.md — read it first and treat its cross-cutting calls (stack & versions, data model, security boundaries, the seams new code plugs into) as already decided. Inherit them; don't reopen them. Plan only what's left at the ticket level: the specific files, the local patterns to mirror, the tests. If a ticket genuinely needs to break an epic-level decision, flag it in Open Questions rather than silently diverging.

Planning Process

Phase 1: Feature Understanding

Deep Feature Analysis:

  • Extract the core problem being solved
  • Identify user value and business impact
  • Determine feature type: New Capability/Enhancement/Refactor/Bug Fix
  • Assess complexity: Low/Medium/High
  • Map affected systems and components

Create User Story Format Or Refine If Story Was Provided By The User:

As a <type of user>
I want to <action/goal>
So that <benefit/value>

Phase 2: Codebase Intelligence Gathering

Use specialized agents and parallel analysis:

1. Project Structure Analysis

  • Detect primary language(s), frameworks, and runtime versions
  • Map directory structure and architectural patterns
  • Identify service/component boundaries and integration points
  • Locate configuration files (pyproject.toml, package.json, etc.)
  • Find environment setup and build processes

2. Pattern Recognition (Use specialized subagents when beneficial)

  • Search for similar implementations in codebase
  • Identify coding conventions:
    • Naming patterns (CamelCase, snake_case, kebab-case)
    • File organization and module structure
    • Error handling approaches
    • Logging patterns and standards
  • Extract common patterns for the feature's domain
  • Document anti-patterns to avoid
  • Check CLAUDE.md for project-specific rules and conventions

3. Dependency Analysis

  • Catalog external libraries relevant to feature
  • Understand how libraries are integrated (check imports, configs)
  • Find relevant documentation in docs/, ai_docs/, .claude/references or ai-wiki if available
  • Note library versions and compatibility requirements

4. Testing Patterns

  • Identify test framework and structure (pytest, jest, etc.)
  • Find similar test examples for reference
  • Understand test organization (unit vs integration)
  • Note coverage requirements and testing standards

5. Integration Points

  • Identify existing files that need updates
  • Determine new files that need creation and their locations
  • Map router/API registration patterns
  • Understand database/model patterns if applicable
  • Identify authentication/authorization patterns if relevant

Clarify Ambiguities — GATE:

Codebase analysis is done, so the open questions are now specific. This is the one moment where you know enough to ask well and have not yet written anything. GATE means: post the questions, then stop. End the turn and wait for the answers. Do not ask and answer in the same breath, and do not roll into Phase 3.

Ask in one cluster, numbered, 3-6 questions max, each carrying a recommended default so answering is cheap ("I'll mirror the first unless you say otherwise"). Draw them only from what the analysis actually left open:

  1. Scope boundary — the adjacent thing a reasonable reader would assume is in scope. Confirm it is out.
  2. Pattern fork — two existing patterns both fit. Name both with file:line and ask which to mirror.
  3. Contract shape — the API surface, payload, or data-model change the ticket implies but never states.
  4. Failure behavior — what happens on the error path the ticket is silent about.
  5. Preference — a library or trade-off with no precedent in this codebase to inherit.
  6. Done —
阅读完整来源 ↗