AI-Assisted Development Template

My opinionated template for structuring AI guidance files in projects. Works with Claude Code and Superpowers.

Usage

Tell your agent:

"Set up AI-assisted development workflows based on https://github.com/mcsdodo/ai-assisted-dev-template"

The agent will read this template, copy relevant files, and adapt [PLACEHOLDER] values to your project.

File Index

Adapt to Project

These files contain [PLACEHOLDER] markers that the agent should replace with project-specific values:

File	Purpose
CLAUDE.md	Main AI guidance - documentation workflow, project structure, conventions
.claude/skills/release-skill/SKILL.md	Release workflow - version files, build/test commands
.claude/SETUP.md	Customization guide for release workflow

Copy As-Is

These files work out of the box - copy without modification.

Note on Superpowers Integration: The review/planning skills below are orchestration layers, not replacements for Superpowers. They invoke Superpowers skills internally while adding structured workflows. Use both together.

Template Skill	Superpowers Used	What Template Adds
task-plan-skill	brainstorming, writing-plans	Structured _tasks/{NN}-{name}/ folders with 01-task.md, 02-plan.md templates
verify-skill	Recommends verification-before-completion	Lightweight checklist + changelog/git status checks
code-review-skill	code-reviewer	2-phase workflow (findings → approval → fixes), _code-review.md artifact, max 4 iterations
plan-review-skill	(standalone)	Reviews existing plans, _plan-review.md artifact, iterative quality gate
test-review-skill	(standalone)	Coverage gap analysis, _test-review.md artifact, iterative quality gate

File	Purpose
CHANGELOG.md	Version history (Keep a Changelog format)
DECISIONS.md	Decision log (ADR/BIZ format)
_tasks/CLAUDE.md	Task planning conventions (with _done/ archive)
_tasks/TASK-STATUS-INDEX.md	Central task status dashboard
_tasks/_done/.gitkeep	Archive folder for completed tasks
_tasks/_TECH_DEBT/CLAUDE.md	Tech debt documentation guidelines
_tasks/_TECH_DEBT/_done/.gitkeep	Archive folder for fixed tech debt
.claude/settings.json	Permissions allowlist + hooks configuration
.claude/hooks/post-commit-reminder.sh	Post-commit changelog reminder hook
.claude/rules/README.md	Path-scoped rules explainer (native Claude Code feature)
.claude/rules/_example.md	Example path-scoped rule file
.claude/skills/task-plan-skill/SKILL.md	Task planning workflow
.claude/skills/decision-skill/SKILL.md	Decision recording workflow
.claude/skills/changelog-skill/SKILL.md	Changelog update workflow
.claude/skills/verify-skill/SKILL.md	Verification before completion
.claude/skills/release-skill/SKILL.md	Release workflow (bump, commit, tag, push)
.claude/skills/code-review-skill/SKILL.md	Iterative code review (max 4 iterations)
.claude/skills/plan-review-skill/SKILL.md	Plan/design review
.claude/skills/test-review-skill/SKILL.md	Test coverage review
.claude/skills/updating-docs-skill/SKILL.md	Documentation update workflow (locality principle)
.claude/skills/move-to-done-skill/SKILL.md	Verify-and-archive completed tasks/tech-debt
.claude/skills/upstream-sync-skill/SKILL.md	Learn from a descendant project and sync refinements back

Examples Only (Reference)

These exist to show patterns - understand them, then delete:

File	Purpose
_tasks/00-example/01-task.md	Example task description
_tasks/00-example/02-plan.md	Example implementation plan
_tasks/_TECH_DEBT/README.md	Example tech debt index table

Template Maintenance (Skip)

These are for maintaining the template itself - do not copy to projects:

File	Purpose
_template/	Template development docs, sync analyses, workflows

Core Concepts

• Documentation-Driven Development: Read docs → Code → Update docs
• Locality Principle: Docs live close to the code they describe
• Task Planning: Complex features get _tasks/{NN}-{name}/ folders

Skills

Invoke by skill name (e.g., changelog-skill) or let natural-language requests trigger auto-activation via their descriptions.

Skill	Purpose
task-plan-skill	Plan complex features with structured task folders
decision-skill	Record architectural (ADR) or business (BIZ) decisions
changelog-skill	Update changelog immediately after completing work
verify-skill	Run verification checks before marking work complete
release-skill	Bump version, update changelog, commit, tag, push
move-to-done-skill	Verify a completed task and archive it to _done/
updating-docs-skill	Which docs to update after code changes (locality principle)
code-review-skill / plan-review-skill / test-review-skill	Iterative reviews with 2-phase approval
upstream-sync-skill	Learn from a descendant project and sync refinements back

Links

• Claude Code
• Superpowers Skills