agentleFS
alex-voloshin-devalex-voloshin-dev/ai-skills/.agents/skills/plan/SKILL.md

plan

Skill2 starsChanged 6 months agoMITView on GitHub

Plan feature implementation across services and roles — parse requirements, understand project architecture (`ARCHITECTURE.md`, `AGENTS.md`), decompose into work packages per service/role, estimate complexity, produce an actionable implementation plan. Part of the umbrella feature workflow. Includes mandatory multi-reviewer feedback loop with product-manager, solution-architect, and system-architect.

184 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use context-optimize, heartmula and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • SireJeffSkill

    context-optimize

    Context Optimization - Orchestrate RPI workflow TODO generation with interactive scoping

    Also in 4 projects that use this

  • math-incSkill

    heartmula

    Set up and run HeartMuLa, the open-source music generation model family (Suno-like). Generates full songs from lyrics + tags with multilingual support.

    Also in 9 projects that use this

  • Tommy-ywSkill

    webhook-subscriptions

    Create and manage webhook subscriptions for event-driven agent activation, or for direct push notifications (zero LLM cost). Use when the user wants external services to trigger agent runs OR push notifications to chats.

    Also in 5 projects that use this

  • math-incSkill

    minecraft-modpack-server

    Set up a modded Minecraft server from a CurseForge/Modrinth server pack zip. Covers NeoForge/Forge install, Java version, JVM tuning, firewall, LAN config, backups, and launch scripts.

    Also in 5 projects that use this

  • john-data-chenSkill

    touchdesigner-mcp

    Control a running TouchDesigner instance via twozero MCP — create operators, set parameters, wire connections, execute Python, build real-time visuals. 36 native tools.

    Also in 6 projects that use this

  • gaebalaiSkill

    codex-system

    PROACTIVELY consult Codex CLI, your highly capable supporter with exceptional reasoning and task completion abilities. Codex is a trusted expert you should ALWAYS consult BEFORE making decisions on: design choices, implementation approaches, debugging strategies, refactoring plans, or any non-trivial problem. When uncertain, consult Codex. Don't hesitate - Codex provides better analysis. Explicit triggers: "think deeper", "analyze", "second opinion", "consult codex".

    Also in 3 projects that use this

  • +3 more from math-inc

The file

Show its rules and text

We split this skill into the rules it gives an agent

14 rules. 0 are common, 10 are distinctive, and 4 are very specific to this project.

  • 0

    Common

    Most of the 168 edited versions we read keep these.

  • 10

    Distinctive

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Read every provided document thoroughly

    line 33
  2. Distinctive:

    If the specification is ambiguous or incomplete — ask before proceeding.

    line 41
  3. Distinctive:

    Read and internalize the project's structure to plan correctly:

    line 45
  4. Distinctive:

    Read the following files (if they exist):

    line 49
  5. Distinctive:

    If documentation is incomplete or absent, scan the filesystem:

    line 64
  6. Distinctive:

    Create a map of services/modules the feature touches:

    line 79
  7. Distinctive:

    Only include work streams that the feature actually requires.

    line 114
  8. Distinctive:

    Wait for user approval. The user may reorder, split, merge, or remove work packages.

    line 223
  9. Very specific:

    After the plan is approved, apply product-manager role and update FEATURES.md:

    line 251
  10. Very specific:

    If FEATURES.md does not exist — create it at the project root

    line 253
  11. Very specific:

    Add or update the feature entry with status planned

    line 254
  12. Very specific:

    If the feature has a PRD or spec — save it in features/ directory and link from FEATURES.md

    line 255
  13. Distinctive:

    After approval, guide execution:

    line 259
  14. Distinctive:

    Update the plan if scope changes during implementation

    line 264

“Common” is measured: kept by at least 6 in 10 of the 168 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Feature Plan

Plan a feature implementation by understanding the project architecture, decomposing work into service-level and role-level packages, and producing an actionable plan. This is the planning phase — no code is written here. Output feeds into feature-dev skill for execution.

1. Receive Feature Requirements

Gather the feature specification from the user:

  • Accepted formats: PRD, ARD, design doc, implementation plan, ticket/issue, verbal description
  • Read every provided document thoroughly
  • Extract and organize:
    • Goal: What the feature does (1–2 sentences)
    • Requirements: Functional (what it does) and non-functional (performance, security, compliance)
    • Acceptance criteria: How to verify the feature works
    • Constraints: Deadlines, compatibility, dependencies on other teams/services
    • Out of scope: What this feature explicitly does NOT cover

If the specification is ambiguous or incomplete — ask before proceeding. Do not assume missing requirements.

2. Understand Project Architecture

Read and internalize the project's structure to plan correctly:

2a. Read Architecture Documentation

Read the following files (if they exist):

  1. ARCHITECTURE.md — system overview, component boundaries, data flow, service map
  2. AGENTS.md (root) — tech stack declaration, project structure, conventions
  3. Subdirectory AGENTS.md files — per-service/module context and stack info

Extract:

  • Service/module boundaries (monolith modules, microservices, frontend/backend split)
  • Tech stack per service (language, framework, database, messaging)
  • Communication patterns (REST, gRPC, events, shared DB)
  • Data flow relevant to the feature
  • Deployment topology (monorepo vs polyrepo, shared vs independent deploys)

2b. Scan Project Structure

If documentation is incomplete or absent, scan the filesystem:

// turbo
ls -la (or dir for Windows)

Look for:

  • Monorepo signals: packages/, services/, apps/, root package.json with workspaces, Nx/Turborepo config
  • Polyrepo signals: Single service, one AGENTS.md, one tech stack
  • Infrastructure: terraform/, infra/, k8s/, helm/, docker-compose.yml
  • Dependency files: package.json, pom.xml, requirements.txt, go.mod, *.csproj per service

2c. Build Service Map

Create a map of services/modules the feature touches:

## Service Map

| Service/Module | Tech Stack | Role | Affected by Feature |
|---|---|---|---|
| [name] | [lang + framework] | `role-id` | [yes/no — how] |
| [name] | [lang + framework] | `role-id` | [yes/no — how] |
| infrastructure | Terraform / K8s | `devops-engineer` role | [yes/no — how] |

3. Decompose into Work Packages

Break the feature into work packages — each package is a self-contained unit of work scoped to one service/module and one role.

3a. Identify Work Streams

Group changes by responsibility:

Work StreamRoleScope
Frontendfrontend-engineer roleUI components, pages, client-side logic, API integration
Backend APIjava-engineer role / python-engineer roleEndpoints, business logic, data access, validation
Data Layerdb-engineer roleDatabase schema, migrations, queries, indexing, optimization
Infrastructuredevops-engineer roleTerraform, Docker, K8s, config, secrets
Cloud Architecturecloud-architect roleCloud platform design, landing zones, networking, cost optimization
CI/CD Architecturedevops-architect rolePipeline design, deployment strategy, GitHub org governance, platform engineering
ML / Dataml-engineer roleModels, pipelines, feature engineering. For LLM/RAG/agent features also consult context-engineering skill
Data Pipelinesdata-engineer roleETL/ELT, data warehousing, Spark, dbt, Airflow
Mobilemobile-engineer roleReact Native, Flutter, iOS, Android apps
Marketing Contentmarketing-strategist rolePositioning, messaging, GTM, landing pages
Architecturesystem-architect roleSystem design, ARCHITECTURE.md, component boundaries, tech selection
Cross-cuttingsoftware-engineer roleShared libraries, contracts, API specs

Only include work streams that the feature actually requires. Do not add empty streams.

3b. Define Work Packages

For each work stream, create ordered work packages:

### [Work Stream]: [Service Name] — `role-id`

#### WP-[N]: [Title]
- **Description**: What to implement
- **Files**: Expected files to create/modify
- **Dependencies**: Which WPs must complete first
- **Acceptance criteria**: How to verify this WP is done
- **Complexity**: S (hours) / M (day) / L (days) / XL (week+)

Rules for decomposition:

  • Each WP is independently testable
  • WPs within a stream are ordered by dependency (foundations first)
  • Cross-service dependencies are explicitly marked
  • Database migrations always come before code that uses them
  • API contracts defined before consumer implementation

3c. Define Integration Points

For features spanning multiple services, explicitly document:

<integration_points>

  • API contracts: Request/response schemas for new or modified endpoints
  • Events/messages: New event types, payload schemas, producers, consumers
  • Shared types: DTOs, enums, or constants shared across services
  • Database changes: Schema migrations, new tables/columns, index requirements
  • Configuration: New env vars, feature flags, secrets needed </integration_points>

4. Dependency Graph

Visualize the execution order:

## Dependency Graph

WP-1: [DB migration]
  └─► WP-2: [Backend API]
        ├─► WP-3: [Frontend integration]
        └─► WP-4: [Infrastructure/config]
WP-5: [Tests] ← depends on WP-2, WP-3

Identify:

  • Critical path: Longest chain of dependent WPs — determines minimum timeline
  • Parallelizable: WPs that can be worked on simultaneously by different roles
  • Blockers: External dependencies (other teams, third-party APIs, approvals)

5. Risk Assessment

Evaluate risks for each work stream:

RiskImpactLikelihoodMitigation
[risk description]High/Med/LowHigh/Med/Low[mitigation strategy]

Common risks to evaluate:

  • Breaking changes to existing APIs (backward compatibility)
  • Database migration on large tables (performance, downtime)
  • Cross-service coordination (deployment order matters)
  • New dependencies or services (operational complexity)
  • Security implications (new auth flows, data exposure)

6. Present the Plan

Compile the full plan and present to the user:

# Feature Plan: [Feature Name]

## Goal
[1–2 sentences]

## Architecture Impact
- Services affected: [list]
- New services: [if any]
- Database changes: [yes/no — summary]
- Infrastructure changes: [yes/no — summary]

## Work Packages

### Stream 1: [name] — `role-id`
| WP | Title | Complexity | Dependencies | Status |
|----|-------|------------|--------------|--------|
| WP-1 | [title] | M | — | planned |
| WP-2 | [title] | S | WP-1 | planned |

### Stream 2: [name] — `role-id`
| WP | Title | Complexity | Dependencies | Status |
|----|-------|------------|--------------|--------|
| WP-3 | [title] | L | WP-1 | planned |

## Critical Path
WP-1 → WP-2 → WP-5 (estimated: [timeframe])

## Risks
[table from Step 5]

## Next Step
Run `feature-dev` skill per work package, applying the designated role.

Wait for user approval. The user may reorder, split, merge, or remove work packages.

7. Multi-Reviewer Feedback Loop

The Feature Plan MUST pass a mandatory multi-reviewer cycle before handoff. Do not update FEATURES.md or hand off to the feature-dev skill until every reviewer returns approved.

Reviewer Panel

Apply each role below in sequence, treating each as an independent reviewer with its own pass over the plan:

  • product-manager role — scope alignment with the PRD, WP coverage of acceptance criteria, risk coverage, correct prioritization, missing requirements
  • solution-architect role — end-to-end design coherence, integration points, API contracts, cross-service coordination, tech stack fit per WP, non-functional requirements coverage
  • system-architect role — system boundaries, component topology, data flow, ARCHITECTURE.md consistency, scalability and deployment implications of the WP decomposition

Cycle

  1. For each role, produce a findings report: Critical (must fix), Major (should fix, justify if waived), Minor (optional), plus an explicit verdict: approved / approved-with-changes / rejected. Keep reports separate per role
  2. Collect all three reports before editing
  3. Apply all actionable findings to the plan (re-scope WPs, adjust dependencies, add missing streams, revise complexity). Resolve conflicts with priority Critical > Major > Minor; on ties, system-architect > solution-architect > product-manager. Record waivers with a one-line rationale
  4. Re-run the same three reviewer passes against the updated plan
  5. Loop until every reviewer returns approved with zero remaining critical/major findings

Termination: pass when all three are approved. On divergence (findings not shrinking, mutually exclusive asks) — pause and ask the user to arbitrate. Max 5 cycles before escalation.

Record the review history at the bottom of the plan as a ## Review History section listing each cycle's reviewer verdicts and open issue counts.

8. Update FEATURES.md

After the plan is approved, apply product-manager role and update FEATURES.md:

  1. If FEATURES.md does not exist — create it at the project root
  2. Add or update the feature entry with status planned
  3. If the feature has a PRD or spec — save it in features/ directory and link from FEATURES.md

9. Handoff to Implementation

After approval, guide execution:

  • Sequential (single developer): Execute WPs in dependency order using feature-dev skill for each
  • Parallel (multiple developers/sessions): Assign independent WPs to separate sessions, each applying the appropriate role
  • Track WP status: planned → in_progress → done
  • Update the plan if scope changes during implementation

Integration

  • Input: PRD, ARD, design doc, or user request
  • Preceded by: product skill (produces PRD), architecture skill (produces ARD, design docs, API contracts, engineering estimates)
  • Followed by: feature-dev skill (implementation per work package)
  • Roles: product-manager role (requirements; Step 7 reviewer), solution-architect role + system-architect role (architecture; Step 7 reviewers), cloud-architect role (cloud platform), devops-architect role (CI/CD architecture), stack-specific roles (work packages)
  • Skills: context-engineering skill (context pipeline design, RAG, memory, agent harness — for AI/LLM feature work packages)

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.