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.

Mini Lifecycle (Quick Fixes)

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

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

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:

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:

Handling Review Findings

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

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.