feature-planning_skill

Overview

This skill creates structured, agent-friendly implementation plans for complex features and stores them under ~/.ai/plans. It enforces progressive disclosure, phase-based rollouts, and a strict directory/file layout so implementation agents can pick up work with minimal context loss. Use it when a feature requires multi-PR delivery, clear acceptance criteria, and preserved decision history.

How this skill works

When invoked manually, the skill generates a complete plan directory for a feature in kebab-case under ~/.ai/plans/{feature-name}/. The plan includes overview.md, spec.md, implementation-guide.md, one or more phase directories (each with files-to-modify.md, technical-details.md, testing-strategy.md), and a shared/ folder for architecture decisions and schema notes. The structure is exact and immutable: agents read these paths directly, so file names and phase naming conventions must match the template exactly.

When to use it

• Planning complex features that will be delivered across multiple pull requests
• Creating handoff-ready documentation for other agents or engineers
• Preserving architectural decisions and rationale for future work
• Enforcing test-first and verification-gated phase progression
• Preparing a feature that affects multiple systems or requires migrations

Best practices

• Name the feature directory in kebab-case and follow phase-{NN}-{kebab-name} exactly
• Start with a concise overview.md to enable progressive disclosure
• Write spec.md as the authoritative, frozen requirements document once implementation starts
• Keep each phase self-contained: files-to-modify.md first, technical-details.md second, testing-strategy.md third
• Create a phase commit after verification that matches the required commit message format to gate progress

Example use cases

• Add a new API-backed user setting that requires DB migration and feature flags spanning three rollouts
• Design a search-indexing feature that needs incremental data backfills and performance tests
• Introduce analytics event collection: foundation schema + event pipeline + dashboard integration
• Refactor authentication flows with staged compatibility and rollback plan
• Implement an experimental UI component that requires backend toggles and gradual rollout