Skip to content

DEVLOG.md

Latest commit

 

History

History
115 lines (84 loc) · 7.48 KB

DEVLOG.md

File metadata and controls

115 lines (84 loc) · 7.48 KB

claude-plans-skill — Development Log

A living record of architectural decisions, milestones, key insights, and strategic direction. Auto-maintained via claude-devlog-skill. Entries are reverse-chronological.

[2026-03-29] Added in-file status markers, rejected status, and plan review on archive

Category: feature Tags: status-markers, rejected, plan-review, context-management, skill-behavior Risk Level: med Breaking Change: yes

Summary

Added > Status: line to plan file headers so Claude can identify stale plans when reading files directly. Added "rejected" as a fifth status value. Expanded status change workflow and added active-plan review during archiving.

Detail

  • Added > Status: \active`` line to plan file header template, between Archived and Maintained lines
  • Status in file header must always match INDEX.md; both are updated together on any status change
  • Added rejected status: "Created but never acted on; no longer relevant"
  • Replaced narrow "Marking a Plan Executed" workflow with general "Changing Plan Status" workflow covering all transitions (executed, superseded, rejected, archived) with trigger phrases for each
  • Added "Reading Plan Files Directly" section: check > Status: line first, treat non-active plans as historical only, handle legacy files without status lines by checking INDEX.md
  • Added plan review step to archiving workflow (Step 4): when archiving a new plan, scan INDEX.md for other active plans in the same project and prompt user to update stale ones
  • SKILL.md grew from 227 to 253 lines (+26)

Decisions Made

  • Status in file header (not just INDEX.md): INDEX.md is the master index, but plans are often referenced by file path in devlogs, roadmaps, and conversations. If Claude reads the file directly, the in-file status prevents acting on a stale plan.
  • "rejected" over "abandoned" or "cancelled": "Rejected" is precise: the plan was evaluated and not adopted. "Abandoned" implies work started and stopped. "Cancelled" implies external force.
  • Plan review piggybacked on archiving: Rather than a separate manual audit, the review triggers automatically when archiving a new plan.

Related

  • Plan: code-katz/claude-plans-skill/plans/2026-03-29-plans-status-markers.md
  • Companion change: claude-devlog-skill deprecation markers (same session)

[2026-03-26] Added lint check requirement to SKILL.md

Category: feature Tags: lint, code-quality, skill-behavior, cross-tool Risk Level: low Breaking Change: no

Summary

Added a "Lint Check" subsection after Session Start Behavior, requiring the skill to verify the target project has a linter configured when identifying a project for plan archiving.

Detail

  • New subsection placed after "Session Start Behavior", before "Error Handling"
  • Framed as "when identifying the project for plan archiving" since the plans skill has no formal Project Context section
  • Checks for stack-appropriate lint config: Ruff (Python), ESLint/Biome (JS/TS), SwiftLint (Swift), golangci-lint (Go), clippy (Rust), pre-commit (general)
  • Part of a cross-tool effort to standardize lint checks across all code-katz tools

Decisions Made

  • After Session Start Behavior rather than at the top — plans skill discovers its project during archiving, not at session start like devlog/roadmap, so the check belongs where project identification actually happens

[2026-03-21] Plans skill v2.0 — project-local archives with global index

Category: refactor Tags: plan-skill, skill-design, v2, architecture Risk Level: med Breaking Change: yes

Summary

Redesigned the plans skill from a centralized global archive (~/.claude/plans/archive/) to a project-local model where plans live in <project>/plans/ with a global lookup index at ~/.claude/plans/INDEX.md.

Detail

The v1.0 design stored all archived plans in a single global directory (~/.claude/plans/archive/). While functional, this decoupled plans from their projects — browsing a project directory didn't reveal its plans, and plans weren't co-located with the code they described.

The v2.0 design:

  • Plans are saved to <project-directory>/plans/YYYY-MM-DD-slug.md
  • Each plan file includes a header referencing back to the original ~/.claude/plans/<random-slug>.md source
  • A global ~/.claude/plans/INDEX.md serves as a cross-project lookup table mapping slugs → project-local files
  • INDEX.md columns: Date, Slug, Project, Title, Local Plan path, Status

The global INDEX.md replaces the per-archive INDEX.md. Plans are now discoverable both locally (browse the project) and globally (search the index).

Decisions Made

  • Project-local over centralized archive — Plans are project artifacts, not tool config. They belong with the project they describe. The v1.0 "plans are tool config" framing was wrong.
  • Global INDEX.md at ~/.claude/plans/ (not archive/) — The index is the only global artifact. Archive subdirectory is eliminated.
  • Slug column in INDEX.md — One slug file can produce multiple project-local plans (e.g., misty-conjuring-hammock contained both a Code Katz and d20m plan). The slug column captures this relationship.
  • Source reference in plan header — Each local plan file references its original slug file, preserving the breadcrumb back to Claude's auto-generated output.

Related

  • [2026-03-20] claude-plan-skill v1.0 — initial design and release (superseded by this entry)
  • First plans archived under v2.0: code-katz/plans/2026-03-21-marketing-messaging.md, d20m/plans/2026-03-21-product-analysis.md

[2026-03-20] claude-plan-skill v1.0 — initial design and release

Category: milestone Tags: plan-skill, skill-design, v1 Risk Level: low Breaking Change: no

Summary

Designed and built the first version of the plans archiving skill. Archives finalized Claude Code plan mode output to a global named archive at ~/.claude/plans/archive/ with an INDEX.md index table.

Detail

Motivation: Claude Code accumulates random-slug plan files in ~/.claude/plans/ with no index or project association. A previous /plans skill existed but used a repo-based / git-commit design — plans are Claude config artifacts, not project source files. This skill uses a global archive with no git dependency.

The skill pairs with devlog-skill: plans capture the "how before execution," devlog captures the "what was decided and why."

A small but notable design touch: the original random-slug filename (e.g., vast-coalescing-cookie) is preserved in the header of each archived plan file as a breadcrumb back to the source.

Decisions Made

  • Global archive (~/.claude/plans/archive/) over per-project repo — plans are tool configuration, not source code. The previous skill's repo-based design was the wrong model.
  • No git/commit requirement — simpler, works without any repo context, appropriate for a global config artifact
  • Two statuses for replaced plans: archived (saw implementation work) vs superseded (replaced before that). Default to archived when unsure.
  • Prefer reading from ~/.claude/plans/<slug>.md over conversation extraction — it's the canonical plan mode output
  • Proactive suggestion at plan finalization, not automatic archiving — user makes the "this is final" call
  • Preserve original slug in archive header — the random slug names are fun and serve as a breadcrumb to the source file