My project lifecycle

Project Lifecycle

Plan → Build → Review → Document → Ship.

⚡ Quick Start

Starting a new feature or system? → Plan first. Use @skills/grill-with-docs if the domain model is unclear or terminology needs sharpening. Otherwise, sketch the approach and start building.

Feature feels complete? → Review before shipping. Invoke @skills/my-code-review for critical paths. Fix critical findings before commit; warnings can be next commit.

About to end session? → Document what was built. Update CONTEXT.md with new terms. Create ADR if a hard-to-reverse decision was made. Write review notes if the code is significant.

Work complete, reviewed, and documented? → Ship via @skills/my-vcs-hygiene. Commit, push, suggest merge.

Activation Condition

This skill activates when the agent is planning, reviewing, documenting, or reflecting on work.

Apply these rules when:

• Starting a new feature or system
• Deciding whether to plan more or start building
• A feature feels complete — what comes next?
• Determining when and what to review
• Documenting what was built (CONTEXT.md, ADRs, review notes)
• The user asks to reflect on a session or update skills

Do not apply these rules when:

• The user issues a VCS command → use @skills/my-vcs-hygiene
• The user asks about worktrees → use @skills/my-workflow

Scope

This skill covers agent behavioral rules for:

• Project lifecycle phases (Plan → Build → Review → Document → Ship)
• When to plan vs. when to just build
• When to invoke code review and how to handle findings
• Post-build documentation (CONTEXT.md, ADRs, reviews)
• Skill self-improvement after shipping

It does not cover:

• Commit/push discipline → @skills/my-vcs-hygiene
• Worktree management → @skills/my-workflow

Project Lifecycle

┌─────┐    ┌──────┐    ┌───────┐    ┌──────────┐    ┌─────┐
│ Plan│ → │ Build│ → │ Review│ → │ Document │ → │ Ship│
└─────┘    └──────┘    └───────┘    └──────────┘    └─────┘

Each phase has an exit condition. Don't skip phases unless the work is trivial.

Phase	Exit Condition	Skip If
Plan	Shared understanding of domain and approach	Trivial fix AND < 3 files AND < 10 tool calls
Build	Feature works, tests pass	—
Review	Critical findings fixed, warnings noted	Trivial fix AND < 3 files AND < 10 tool calls
Document	CONTEXT.md updated, ADRs created if needed	Trivial fix AND no new terminology or behavior introduced
Ship	Committed, pushed, PR/merge suggested	—

Mini Lifecycle (Quick Fixes)

For sessions with < 20 tool calls or < 5 files touched:

┌─────────┐    ┌─────────┐    ┌─────┐
│  Intent │ → │  Verify │ → │ Ship│
└─────────┘    └─────────┘    └─────┘

Phase	Duration	Checkpoint
Intent	1 sentence	State what changed and why: "Fixing typo in README that broke the install link."
Verify	1 tool call	read the changed file to confirm the edit is correct. If config, bash to validate syntax.
Ship	1–2 tool calls	Commit with a descriptive message. No review subagent needed.

When to skip Mini Lifecycle:

• Pure whitespace/formatting changes (agent auto-formats)
• Changes to untracked scratch files (progress.md, local notes)
• Changes inside a worktree where user explicitly said "just fix it, I'll review later"

Escalation rule: If a Mini Lifecycle session exceeds 20 tool calls, pause and assess whether the full Plan→Build→Review→Document→Ship lifecycle should apply.

Plan Phase

Decide how much planning a task needs:

Signal	Action
New domain, unfamiliar terminology, cross-cutting concerns	Use @skills/grill-with-docs. Produce CONTEXT.md and ADRs before building.
Well-understood domain, clear scope, familiar codebase	Sketch approach in 1–2 sentences, then start building.
"Just fix this bug" or "update this config"	Skip planning. Go straight to Build.

Rule of thumb: If you'd need to explain the domain to another developer, plan first. If the change is obvious from the codebase, build first.

Plan Phase Exit Checklist

Before leaving Plan and entering Build:

• Approach is sketched and shared
• If any non-trivial choice was made (library, pattern, scope), log it via @skills/my-decision-log
• If no non-trivial choices, skip decision logging

Why mandatory: my-decision-log adherence is 5–15% because it is standalone. Piggybacking on the stronger lifecycle skill doubles activation. Log decisions immediately — do not defer to Document phase where context may be compacted.

Build Phase

While building, consult @skills/my-vcs-hygiene for commit discipline and visual iteration rules.

Build Phase Decision Capture

During Build, if a pivot or trade-off emerges:

• Pause and log via @skills/my-decision-log immediately
• Do not defer to Document phase — context may be compacted

Examples of decisions to log:

• Switched from library A to library B mid-build
• Narrowed or expanded scope from original plan
• Chose one pattern over another with genuine alternatives
• Deferred a sub-task to a follow-up session

Build Exit Checklist

• Feature works as intended
• No obvious regressions
• Tests pass (if project has tests)
• Code is in a commitable state

If any item is missing, keep building. Don't proceed to Review with broken code.

Review Phase

Invoke @skills/my-code-review at natural breakpoints:

When	Why
After completing a major feature	Catch design issues before they fossilize
Before shipping critical paths	Security, performance, correctness
When the user asks "review this"	Direct request — honor it
After a refactor that touched > 10 files	Refactors are review-prone

Handling Review Findings

Severity	Action
Critical (security, correctness, crash)	Fix before committing. Amend or new commit.
Warning (maintainability, idioms)	Fix in next commit, or note for follow-up.
Suggestion (nice-to-have)	Optional. Mention to user, let them decide.

Don't let perfect be the enemy of shipped. A warning about naming can be fixed later. A critical bug cannot.

Document Phase

After building and reviewing, document what was built:

CONTEXT.md

Update the glossary if the session introduced or clarified domain terms:

• New terms → add with definition
• Clarified terms → update existing definition
• Removed concepts → delete or mark deprecated

Keep CONTEXT.md implementation-free. It is a glossary, not a spec.

ADRs

Create an ADR only when all three are true:

1. Hard to reverse — changing the decision later is costly
2. Surprising without context — a future reader will wonder "why?"
3. Result of a real trade-off — genuine alternatives existed

If any is missing, skip the ADR. Use the format from @skills/grill-with-docs.

Review Notes

For significant features, create review artifacts:

• review/code-review.md — structured findings from @skills/my-code-review
• review/ux-audit.md — UX/usability findings (if UI involved)

These become reference material for future iterations.

Ship Phase

Hand off to @skills/my-vcs-hygiene:

1. Commit any remaining changes
2. Push to origin
3. Summarize: "Pushed to <branch>. PR: <url>"
4. Suggest merge or next steps

Cross-Skill Commit Trigger

For Mini Lifecycle sessions, the lifecycle skill must explicitly invoke @skills/my-vcs-hygiene at session end if changes exist. Do not wait for a user signal — the user already implicitly approved the intent during the Mini Lifecycle.

For full lifecycle sessions, @skills/my-vcs-hygiene is already triggered by the Ship phase handoff.

Memex Retro Mandate

Every session that called memex_recall must call memex_retro before ending, unless the user explicitly waives with "no retro needed."

• Sessions without memex recall are exempt
• Retro should write at least 1 card per session
• If the session had significant learnings (new pattern, error fix, skill update), write multiple cards

Skill Self-Improvement

After shipping, reflect on the session:

1. What patterns emerged? — visual iteration loops, review → fix cycles, cross-package commits
2. What was awkward? — Did the agent ask permission when it shouldn't? Skip a phase it shouldn't have?
3. Update skills — If a pattern recurs, consider updating @skills/my-workflow, @skills/my-vcs-hygiene, or this skill
4. Save to memex — Use memex_retro for atomic insights that should persist across sessions

When to update skills

Trigger	Action
Same awkward pattern in 2+ sessions	Update the relevant skill
User explicitly says "update my skill"	Update immediately
New tool or workflow adopted	Add to @skills/my-tech-stack or relevant skill
Skill description under-triggers	Optimize description per @skills/skill-creator

Examples

Good: Plan → Build → Review → Document → Ship

1. Plan: Used @skills/grill-with-docs to define "Singularity" and "Health Check" for pi-event-horizon-provider. Produced CONTEXT.md and ADR-0001.
2. Build: Implemented async status widget. Committed via @skills/my-vcs-hygiene.
3. Review: Invoked @skills/my-code-review. Fixed critical feedback (try/finally, widget key, distinct glyphs).
4. Document: Updated CONTEXT.md with widget terminology. Created review/code-review.md and review/ux-audit.md.
5. Ship: User said "looking good. commit it and push" → @skills/my-vcs-hygiene executed directly. Branch created, committed, pushed.

Good: Skipping Plan for Trivial Fix

User: "Fix the typo in the README" Agent: No planning needed. Fixed typo. Committed directly via @skills/my-vcs-hygiene.

Bad: Skipping Review for Major Feature

Agent ships a 500-line feature without review. ❌ Major features need review before shipping.

Bad: Over-Documenting Trivial Changes

Agent creates an ADR for renaming a local variable. ❌ ADRs are for hard-to-reverse, surprising, trade-off decisions.

Decision Tree

Starting new feature?
├── < 20 tool calls OR < 5 files → Mini Lifecycle (Intent → Verify → Ship)
├── Trivial fix but growing scope → Escalate to full lifecycle
├── New domain or unclear terminology → Plan first (@skills/grill-with-docs)
└── Well-understood domain → Brief sketch, then Build

Feature feels complete?
├── Mini Lifecycle → Ship via @skills/my-vcs-hygiene
└── Full lifecycle → Review first (@skills/my-code-review)

Review findings?
├── Critical → Fix before commit
├── Warning → Fix in next commit or note for follow-up
└── Suggestion → Optional, mention to user

About to end session?
├── Mini Lifecycle → Commit and end
├── Full lifecycle → Document first, then commit and end
└── Used memex_recall? → memex_retro before ending

Related Skills

• @skills/my-workflow — Worktrees, direction, naming, session boundaries, parallel agents
• @skills/my-vcs-hygiene — Commit/push discipline, branch-from-main, amend safety, visual iteration
• @skills/grill-with-docs — Stress-test plans against domain model, produce CONTEXT.md and ADRs
• @skills/my-code-review — Research-backed code review before shipping
• @skills/my-semantic-release — Release workflows when a worktree is ready to merge
• @skills/skill-creator — Create or optimize skills, measure performance

Versioning

• Last updated: 2026-05-26
• Version: 1.1
• Update notes: Added Mini Lifecycle (Intent→Verify→Ship for <20 tool calls / <5 files) to replace the overly permissive "< 5 lines" trapdoor. Added mandatory decision-log checkpoints in Plan and Build phases. Added cross-skill commit trigger for Mini Lifecycle. Added memex retro mandate. Addresses VCS collapse in small sessions and 5–15% my-decision-log adherence by piggybacking on the stronger lifecycle skill.