agent-implementation-planning

Defines a five-phase workflow for researching, approving, executing, and verifying implementation plans.

Updated Aug 25, 2026
One-click install
npx skills add https://github.com/hyvanmielenpelit/SharedAgentSkills --skill agent-implementation-planning-hyvanmielenpelit
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: agent-implementation-planning
Source: https://github.com/hyvanmielenpelit/SharedAgentSkills/tree/main/skills/agent-implementation-planning
Command: npx skills add https://github.com/hyvanmielenpelit/SharedAgentSkills --skill agent-implementation-planning-hyvanmielenpelit

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Non-trivial coding tasks handled without a written plan lead to wasted effort, uncoordinated subagents, and unintended breaking changes. This Skill enforces a mandatory research-plan-approve-execute-verify lifecycle so multi-file and cross-layer work is documented, user-approved, and verifiable before any file is edited. ## Core Features & Use Cases - Five-Phase Lifecycle: Research (read-only), write the plan, obtain explicit user approval, execute with progress tracking, and verify with builds, tests, and a walkthrough document. - Shared Plans Repository Protocol: Stores plans in a versioned <organization>/<repository>/YYYY-MM-DD/task_name/ layout with strict _v<N> versioning, document-set harmonization, an allowed-organization allowlist, and a gitignored .plans/ or chat-only fallback tier. - Commit and Push Discipline: Permits git commit/push only in the plans repository, with explicit-path staging, rebase-based conflict recovery, and a ban on committing in any project repository. - Use Case: An agent asked to add SSO login across a backend and client SPA writes implementation_plan_v1.md under hyvanmielenpelit/GnollHack/2025-01-15/sso_login/, waits for approval, executes with subagents, then produces task.md and walkthrough.md with verification results. ## Quick Start Ask the agent to create an implementation plan for your multi-file feature before it edits any code, and approve the plan document it links to you.

Frequently Asked Questions about agent-implementation-planning

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
When is a written implementation plan required for a coding task?

A plan is required when a task touches more than one file, crosses a build or code regeneration boundary, modifies public APIs or database schemas, or is a refactor or new feature. Single-file bug fixes, typo corrections, and read-only investigation do not require one.

How do AI agents share implementation plans across different tools?

Plans are stored as Markdown files in a shared plans Git repository under an organization/repository/date/task directory layout. Any agent in any harness can read the document later, since plans are written for a context-free implementer with absolute paths and explicit decisions.

Can an AI agent commit code changes to a project repository?

No. Under this workflow agents may only run git commit and push inside the dedicated plans repository. In every project repository they write files, leave them uncommitted, and print the commands for a person to run.

What happens if the plans repository is not available?

The workflow falls back to a gitignored .plans/ directory in the main repository, verified with git check-ignore. If that is not ignored either, the plan is written chat-only with no files on disk, while the full format and approval steps still apply.

How are plan document versions managed?

Every document starts at _v1 and revisions create a new file with the next number; existing versions are never overwritten or deleted. Documents in a set are harmonized to the same version number, while task.md and walkthrough.md stay singular.

Why must the orchestrator run builds and tests instead of subagents?

Subagents edit files but never build, test, or lint, because a result produced on a tree that has since changed is not valid verification. The orchestrator runs all builds and tests at plan step boundaries after every subagent has returned.