@jhongutang0116/claude-skills 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jhon Gutang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,114 @@
+# @jhongutang0116/claude-skills
+
+Personal [Claude Code](https://docs.claude.com/en/docs/claude-code) skill library.
+Install the package once, run one command, and the skills land in a project's
+`.claude/skills/` (or `~/.claude/skills/` for every project on the machine) — no
+hand-copying.
+
+## Bundled skills
+
+| Skill | What it does |
+|---|---|
+| `implementation-workflow` | Gated four-phase build pipeline: SRS → Development → Testing → Documentation. Language/framework-agnostic. |
+| `plan-checklist` | Generates and enforces a single `plan.md` build-and-checklist file from an approved SRS. |
+
+Run `npx claude-skills list` to see what a given version ships.
+
+## Install into another project
+
+```sh
+npm install -D @jhongutang0116/claude-skills
+npx claude-skills install                        # all skills
+npx claude-skills install implementation-workflow   # just one (or list several)
+```
+
+This copies each selected skill into `./.claude/skills/<name>/`. Claude Code picks
+them up automatically as project skills. Run `npx claude-skills list` first to see
+the available names.
+
+To keep them in sync on every `npm install`, add to that project's `package.json`:
+
+```json
+{
+  "scripts": {
+    "postinstall": "claude-skills install --force"
+  }
+}
+```
+
+Then either commit `.claude/skills/` or add it to that project's `.gitignore`
+and let `postinstall` regenerate it.
+
+## Install once for every project on the machine
+
+```sh
+npm install -g @jhongutang0116/claude-skills
+claude-skills install --global      # -> ~/.claude/skills/
+```
+
+Re-run after upgrading the package (`npm update -g @jhongutang0116/claude-skills`).
+
+## Install without publishing to npm
+
+Works straight from GitHub — no registry account needed, private repo is fine:
+
+```sh
+npm install -D github:JhonGutang/personal-skill-library
+npx claude-skills install
+```
+
+## CLI
+
+```
+claude-skills install [skill...] [--dir <path>] [--global] [--force] [--dry-run]
+claude-skills list
+claude-skills --help
+```
+
+- `skill...` — names to install; omit to install every bundled skill. An unknown
+  name is rejected with the list of valid ones.
+- `--dir <path>` — target project directory (default: current directory). Skills
+  go into `<path>/.claude/skills/`.
+- `--global` — target `~/.claude/skills/` instead of a project.
+- `--force` — overwrite skills that already exist at the destination.
+- `--dry-run` — print the plan without writing.
+
+```sh
+claude-skills install plan-checklist --dir ../other-project --force
+claude-skills install implementation-workflow --global
+```
+
+## Adding or editing a skill
+
+1. Create `skills/<skill-name>/SKILL.md` with YAML frontmatter (`name`, `description`)
+   plus any `references/`, `assets/`, `scripts/` the skill needs.
+2. `node bin/cli.js list` to confirm it's discovered (a directory counts as a
+   skill only if it contains `SKILL.md`).
+3. Bump the version and publish (below).
+
+## Publishing a new version
+
+```sh
+npm version patch        # or minor / major — commits + tags
+npm publish              # publishConfig.access=public handles scoped visibility
+git push --follow-tags
+```
+
+Publishing needs 2FA on the npm account: either run `npm publish` and enter the
+authenticator OTP when prompted (`--otp=<code>` to pass it inline), or publish
+with a **granular access token** that has "bypass 2FA" enabled (see
+`~/.npmrc` setup below — required for CI).
+
+```sh
+# token-based auth (put in ~/.npmrc, never commit it):
+//registry.npmjs.org/:_authToken=npm_xxxxxxxxxxxxxxxxxxxx
+```
+
+## Local testing before publishing
+
+```sh
+npm pack                 # inspect the .tgz contents
+npm link                 # then, in another project:
+claude-skills install
+npm rm -g @jhongutang0116/claude-skills
+```

package/bin/cli.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+// Sync the bundled Claude Code skills into a project's .claude/skills/
+// (or ~/.claude/skills/ with --global). No runtime dependencies.
+
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  rmSync,
+  cpSync,
+  statSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const SRC = resolve(here, "..", "skills");
+
+const HELP = `claude-skills — sync personal Claude Code skills into a project
+
+Usage:
+  claude-skills install [skill...] [--dir <path>] [--global] [--force] [--dry-run]
+  claude-skills list
+  claude-skills --help
+
+Commands:
+  install   Copy skills into <path>/.claude/skills/. With no skill names,
+            every bundled skill is installed; otherwise only the ones named.
+  list      Print the names of the bundled skills
+
+Flags:
+  --dir <path>   Target project directory (default: current directory)
+  --global       Install into ~/.claude/skills/ instead of a project
+  --force        Overwrite skills that already exist at the destination
+  --dry-run      Show what would happen without writing anything
+
+Examples:
+  claude-skills install
+  claude-skills install implementation-workflow
+  claude-skills install plan-checklist --dir ../other-project --force
+  claude-skills install implementation-workflow --global
+`;
+
+function bundledSkills() {
+  if (!existsSync(SRC)) return [];
+  return readdirSync(SRC)
+    .filter((name) => {
+      const p = join(SRC, name);
+      return statSync(p).isDirectory() && existsSync(join(p, "SKILL.md"));
+    })
+    .sort();
+}
+
+let parsed;
+try {
+  parsed = parseArgs({
+    allowPositionals: true,
+    options: {
+      dir: { type: "string" },
+      global: { type: "boolean", default: false },
+      force: { type: "boolean", default: false },
+      "dry-run": { type: "boolean", default: false },
+      help: { type: "boolean", short: "h", default: false },
+    },
+  });
+} catch (err) {
+  console.error(`${err.message}\n\n${HELP}`);
+  process.exit(1);
+}
+
+const { values, positionals } = parsed;
+const cmd = positionals[0] ?? "install";
+const requested = positionals.slice(1);
+
+if (values.help || cmd === "help") {
+  process.stdout.write(HELP);
+  process.exit(0);
+}
+
+const all = bundledSkills();
+if (all.length === 0) {
+  console.error("No bundled skills found next to this CLI.");
+  process.exit(1);
+}
+
+if (cmd === "list") {
+  for (const s of all) console.log(s);
+  process.exit(0);
+}
+
+if (cmd !== "install") {
+  console.error(`Unknown command: ${cmd}\n\n${HELP}`);
+  process.exit(1);
+}
+
+// --- install ---------------------------------------------------------------
+
+let selected;
+if (requested.length === 0) {
+  selected = all;
+} else {
+  const unknown = requested.filter((s) => !all.includes(s));
+  if (unknown.length > 0) {
+    console.error(`Unknown skill(s): ${unknown.join(", ")}`);
+    console.error(`Available: ${all.join(", ")}`);
+    process.exit(1);
+  }
+  // de-dupe while preserving order
+  selected = [...new Set(requested)];
+}
+
+const dest = values.global
+  ? join(homedir(), ".claude", "skills")
+  : join(values.dir ? resolve(values.dir) : process.cwd(), ".claude", "skills");
+
+const dry = values["dry-run"];
+const force = values.force;
+
+console.log(
+  `${dry ? "[dry-run] " : ""}installing ${selected.length} skill(s) -> ${dest}`,
+);
+if (!dry) mkdirSync(dest, { recursive: true });
+
+let copied = 0;
+let skipped = 0;
+for (const s of selected) {
+  const to = join(dest, s);
+  if (existsSync(to) && !force) {
+    console.log(`  skip   ${s} (already exists — pass --force to overwrite)`);
+    skipped++;
+    continue;
+  }
+  if (!dry) {
+    if (existsSync(to)) rmSync(to, { recursive: true, force: true });
+    cpSync(join(SRC, s), to, { recursive: true });
+  }
+  console.log(`  ${force && !dry ? "update" : "copy  "} ${s}`);
+  copied++;
+}
+
+console.log(`done: ${copied} written, ${skipped} skipped`);

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@jhongutang0116/claude-skills",
+  "version": "1.0.0",
+  "description": "Personal Claude Code skill library — installable into any project's .claude/skills/",
+  "type": "module",
+  "bin": {
+    "claude-skills": "bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "skills"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node bin/cli.js list"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "skills",
+    "agent-skills"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JhonGutang/personal-skill-library.git"
+  },
+  "author": "Jhon Gutang",
+  "license": "MIT"
+}

package/skills/implementation-workflow/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: implementation-workflow
+description: Runs a structured four-phase build workflow for new features or systems — SRS (requirements gathering) → Development → Testing → Documentation. Use this skill whenever the user wants to build, implement, add, or ship a new feature or system, says things like "let's build X", "implement Y", "I want to add Z to the app", asks for a requirements doc/SRS/spec, or wants a structured process for going from idea to shipped, tested, documented code. Also trigger when the user wants to establish or look up project conventions or coding standards before writing code, or wants to resume/continue an in-progress build. Do not trigger for small one-off edits, quick bug fixes, or questions that aren't about building something new end-to-end.
+---
+
+# Implementation workflow
+
+Four sequential phases, always in this order: **SRS → Development → Testing → Documentation**.
+
+Each phase produces a deliverable. Do not move to the next phase until the developer has explicitly signed off on the current one — even if the next step seems obvious. This is a gated pipeline, not a checklist you race through.
+
+## Before doing anything: check for existing work
+
+The developer may be resuming a feature started in an earlier session. Before starting the SRS interview, check `docs/srs/` for a folder matching what they're describing. If one exists:
+- Read its `srs.md` and `checklist.md`.
+- Report current status back to the developer ("Found an in-progress SRS for X — phase 2 is 3/7 checked off").
+- Continue from there instead of starting over.
+
+## Document locations
+
+These are the defaults this skill writes to. If the developer prefers different paths, use theirs instead and keep using them for the rest of the workflow.
+
+| Artifact | Path |
+|---|---|
+| SRS document | `docs/srs/<feature-slug>/srs.md` |
+| Plan + checklist (single file) | `docs/srs/<feature-slug>/plan.md` |
+| Project conventions (fresh repos only) | `docs/conventions/PROJECT-CONVENTIONS.md` |
+| Final feature doc | `docs/features/<YYYY-MM-DD>-<feature-slug>.md` |
+
+The plan + checklist file is generated and enforced by the companion **plan-checklist** skill, triggered automatically right after SRS approval, and consulted constantly through Development and Testing. If that skill isn't installed, fall back to the checklist instructions inside `references/srs-phase.md`.
+
+`<feature-slug>` is a short kebab-case name for the feature (e.g. `user-notifications`).
+
+## The four phases
+
+### Phase 1 — SRS
+Interview the developer until requirements are genuinely clear on both sides, surface tradeoffs and risks honestly, get explicit approval, then write the SRS. Once approved, the **plan-checklist** skill takes over and turns it into `plan.md` — don't write a separate checklist here if that skill is available.
+Full instructions: `references/srs-phase.md`. Template: `assets/srs-template.md`.
+
+### Phase 2 — Development
+Scan the codebase for existing conventions before writing any code — whatever language or stack it's in. If none exist (fresh repo), interview the developer and record the answers so future features don't repeat the interview. Build against `plan.md`, in order — this is what the plan-checklist skill's enforcement rules apply to.
+Full instructions: `references/development-phase.md`. Template: `assets/conventions-template.md`.
+
+### Phase 3 — Testing
+Same scan-first approach as Development. If no test conventions exist, detect the framework and check current best practices online rather than relying on possibly-stale training data, confirm the approach briefly, then write and actually run tests. Keep working against `plan.md`'s Testing section.
+Full instructions: `references/testing-phase.md`.
+
+### Phase 4 — Documentation
+Write a dated feature doc summarizing what shipped, cross-linked with the SRS. This is the final phase — after this, the workflow for this feature is complete.
+Full instructions: `references/documentation-phase.md`.
+
+## Honesty is part of the job
+
+Across all four phases, don't just agree with everything to keep momentum. If a requirement is risky, a shortcut creates real technical debt, a testing gap matters, or an approach conflicts with the project's own conventions, say so plainly and explain the tradeoff — then respect whatever the developer ultimately decides.
+
+## If scope changes mid-build
+
+Don't silently rewrite an already-approved SRS. Add a dated "Addendum" section to `srs.md` recording what changed and why, and update `plan.md`'s Deviation log to match (see the plan-checklist skill).

package/skills/implementation-workflow/assets/conventions-template.md

@@ -0,0 +1,35 @@
+# Project conventions
+
+**Established:** <YYYY-MM-DD>
+
+This file is the source of truth for project conventions. The implementation-workflow skill checks here before ever asking these questions again — update it in place if conventions evolve.
+
+## Architecture
+
+<feature-based / layered / monorepo / etc., and why>
+
+## Folder structure
+
+<pattern, with an example path>
+
+## Naming conventions
+
+<files, components, functions, variables>
+
+## Error handling
+
+<philosophy — how errors surface, logging approach, etc.>
+
+## Required / disallowed libraries
+
+<anything that must or must not be used>
+
+## Domain-specific conventions
+
+<whatever the project type calls for — e.g. state management + styling for a UI app,
+config + logging + migration layout for a service, command/flag structure for a CLI,
+public API and versioning policy for a library. Delete if not applicable.>
+
+## Notes
+
+<anything else the developer specified that doesn't fit above>

package/skills/implementation-workflow/assets/srs-template.md

@@ -0,0 +1,40 @@
+# <Feature title> — SRS
+
+**Date:** <YYYY-MM-DD>
+**Status:** Draft | Approved | In progress | Complete
+
+## Summary
+
+<2-4 plain-language sentences: what this is and why it's being built.>
+
+## Non-goals
+
+- <explicitly out of scope, so it doesn't get assumed back in later>
+
+## Requirements by phase
+
+### Phase 1: <name>
+
+- <requirement>
+
+### Phase 2: <name>
+
+- <requirement>
+
+<add more phase headings as needed — these become the Development phase's roadmap>
+
+## Risks & tradeoffs
+
+- <risk or tradeoff surfaced during the requirements discussion, and the decision made about it>
+
+## Plan & checklist
+
+See [plan.md](./plan.md) for the build plan and checklist (generated by the plan-checklist skill once this SRS is approved).
+
+## Feature doc
+
+<filled in during Phase 4 — link to docs/features/<date>-<slug>.md once it exists>
+
+## Addenda
+
+<dated entries added here if scope changes after approval — do not edit the sections above once approved>

package/skills/implementation-workflow/references/development-phase.md

@@ -0,0 +1,43 @@
+# Phase 2: Development
+
+Goal: write code that looks like it belongs in this codebase, without making the developer re-explain conventions that are already established somewhere in the project.
+
+## 1. Scan first — every time
+
+Do this even if the codebase came up earlier in the conversation; conventions can be inconsistent across a repo, and it's cheap to check.
+
+Gather the following signals with whatever tools fit the stack (directory listing, grep, reading files). This is language- and framework-agnostic — adapt each check to whatever ecosystem the repo actually uses:
+- **Dependency/build manifests** — read the ones that exist (e.g. `package.json`, `pyproject.toml`, `requirements.txt`, `go.mod`, `Cargo.toml`, `pom.xml`, `build.gradle`, `Gemfile`, `composer.json`, `*.csproj`, `mix.exs`). These name the language, framework, and tooling.
+- **Folder structure** — top 2-3 levels, ignoring vendored/build/VCS directories.
+- **Lint/format/type-check/config presence** — whatever the detected ecosystem uses (linter, formatter, type checker, test runner config).
+- **Existing test setup** — test directory layout, file-naming pattern, and the test framework already in use.
+- Whether `docs/conventions/PROJECT-CONVENTIONS.md` already exists — if it does, read it instead of re-interviewing.
+
+Then read 2-3 existing files similar to what you're about to build — declared config isn't always what the code actually does, and the real signal is in the files themselves.
+
+## 2. Branch on what you find
+
+**Established codebase (patterns exist):**
+Adopt what's there — folder structure, naming, module boundaries, error-handling style, and whatever domain-specific patterns the stack has (state management and styling for a UI, middleware and migration layout for a service, command structure for a CLI, public API shape for a library). Before writing much code, post a short summary of what you detected and intend to follow, e.g.:
+
+> Detected: layered structure under `internal/`, errors wrapped with `fmt.Errorf` and `%w`, table-driven tests in `*_test.go` files alongside sources. Building to match.
+
+This gives the developer a cheap chance to correct you before a lot of code exists in the wrong shape.
+
+**Fresh/empty repo (nothing meaningful to detect):**
+Interview the developer on:
+- Architecture style (feature-based vs layered vs something else, and why)
+- Folder structure and naming conventions
+- Error-handling philosophy
+- Any libraries that must or must not be used
+- Any domain-specific conventions the project type calls for (e.g. state management and styling for a UI app, config and logging approach for a service)
+
+Write the answers to `docs/conventions/PROJECT-CONVENTIONS.md` using `assets/conventions-template.md`. This file gets checked on every future run of this skill — the interview should only happen once per project, not once per feature.
+
+## 3. Build against the plan
+
+Work through `plan.md` in order — this file is owned and enforced by the plan-checklist skill, so follow its rules on reading it before every turn, verifying before checking anything off, and logging deviations rather than silently reordering. Don't jump ahead to a later step because it looks easy or more interesting. Flag when a phase-group is done.
+
+## 4. If the SRS turns out to be wrong
+
+If something agreed in Phase 1 turns out to be infeasible, harder than expected, or just a bad idea once you're actually building it — stop and say so. Don't quietly deviate from the agreed plan. Propose the change, get agreement, then record it as an SRS addendum (see main SKILL.md).

package/skills/implementation-workflow/references/documentation-phase.md

@@ -0,0 +1,26 @@
+# Phase 4: Documentation
+
+Goal: leave a durable, dated record of what was built so future work — including future runs of this skill — can find it without re-reading the whole diff history.
+
+This is the final phase. Only start it once every item in `plan.md`'s Testing section is checked off.
+
+## 1. Write the feature doc
+
+Create `docs/features/<YYYY-MM-DD>-<feature-slug>.md` containing:
+- Title and date.
+- A one-paragraph summary (the SRS summary is a good starting point, updated for anything that changed along the way).
+- What was actually built, and the key decisions made during development — especially any deviations from the original SRS.
+- How to run or test it.
+- Known limitations or suggested follow-up work.
+
+## 2. Cross-link with the SRS
+
+- Add a line in the new feature doc linking back to `docs/srs/<feature-slug>/srs.md`.
+- Add a line in `srs.md` pointing forward to the new feature doc now that it exists.
+
+## 3. Close out
+
+- Mark every remaining item in `plan.md` complete, including its own Documentation section, and set its Status line to Complete.
+- Give the developer a short wrap-up: what shipped, across all four phases, and where to find each artifact (SRS, plan, code, tests, docs).
+
+Once this is done, the implementation workflow for this feature is complete.

package/skills/implementation-workflow/references/srs-phase.md

@@ -0,0 +1,50 @@
+# Phase 1: SRS (requirements)
+
+Goal: leave this phase with a requirements document both you and the developer actually agree on — not a document you wrote from a single message and hoped was right.
+
+## 1. Interview
+
+Ask about, over as many turns as it takes:
+- The core problem/goal — what is this actually for, and who's it for?
+- Must-have scope vs nice-to-have vs explicitly out of scope.
+- Constraints: tech stack limits, deadlines, systems this touches or could break.
+- Edge cases the developer may not have thought through yet.
+- Success criteria — how will you both know this is done and working?
+
+Ask one focused question or a small related cluster at a time. Don't front-load fifteen questions in one message — let each answer shape the next question. Keep going until there's genuinely nothing left to clarify, not just until the developer seems to want to move on.
+
+Before calling it converged, restate your understanding in plain language and ask the developer to confirm ("Here's what I've got — is that right?"). Treat silence or a vague "sounds good" as insufficient if there are still open questions on your end.
+
+## 2. Be honest about tradeoffs
+
+This is not optional. Proactively raise, even if unasked:
+- Simpler alternatives that cost less time but give up something.
+- Technical debt a shortcut would introduce.
+- Anything that risks breaking existing functionality.
+- Scaling, security, or maintenance concerns that aren't obvious from the feature request alone.
+
+State the tradeoff and your recommendation, then defer to the developer's call once they've heard it. The goal is an informed decision, not a vetoed one.
+
+## 3. Get explicit approval
+
+Don't write the SRS until the developer clearly signs off — "approved," "let's do it," "write it up," or similar. A lukewarm "ok" after a long back-and-forth is worth double-checking: "Should I write this up as the SRS now?"
+
+## 4. Write the document
+
+Use `assets/srs-template.md` as the starting structure.
+
+`docs/srs/<feature-slug>/srs.md` needs:
+- A summary at the top — 2-4 plain-language sentences on what this is and why.
+- Requirements split into logical build phases (these become the plan's roadmap — order them the way the work should actually happen, not just as a flat feature list).
+- An explicit non-goals section.
+- A risks & tradeoffs section capturing what came up during the interview.
+
+## 5. Hand off to the plan-checklist skill
+
+Once `srs.md` is written and approved, that's the end of this phase — don't write a checklist here. The **plan-checklist** skill triggers automatically right after approval, reads `srs.md`, and produces `docs/srs/<feature-slug>/plan.md`: a single file that's both the build plan and the checklist, and the thing Development and Testing check constantly from here on.
+
+If that skill isn't installed, fall back to writing a simple checkbox list at the bottom of `srs.md` grouped by phase, so there's still something to track progress against.
+
+## 6. Treat the SRS as source of truth
+
+Once written and approved, don't quietly edit it if scope shifts later. Add a dated "Addendum" section instead — see the note in the main SKILL.md.

package/skills/implementation-workflow/references/testing-phase.md

@@ -0,0 +1,29 @@
+# Phase 3: Testing
+
+Goal: tests that match how this project already tests things — or a sound, current default when there's no established pattern yet.
+
+## 1. Scan for existing test conventions
+
+Look for: test file naming and location (e.g. a suffix like `*.test.*` / `*_test.*` / `*.spec.*`, or a dedicated `tests/` / `__tests__/` folder), the test framework already declared in the project's dependency manifest, mocking approach, assertion style, coverage tooling/thresholds.
+
+## 2. If a pattern exists
+
+Match it exactly — same naming, same structure, same assertion style. Don't introduce a second testing convention into a project that already has one, even if you'd personally prefer a different approach.
+
+## 3. If no pattern exists yet
+
+- Detect the framework/language in use from the manifest and folder structure.
+- Web search for that framework's *current* recommended testing setup and best practices before defaulting to what you already know — tooling across every ecosystem moves fast enough that training data can be stale (e.g. search "\<framework\> testing best practices" for the current year rather than assuming).
+- Propose the approach — framework/library choice, file convention, where tests live — to the developer in one short message before writing a large number of tests. This is a lighter check-in than the Phase 1 interview: a quick confirm-or-redirect, not a long back-and-forth.
+
+## 4. Write, then actually run
+
+Write the tests, then run them for real and iterate until they pass — don't write tests and assume correctness without executing them.
+
+Update `plan.md`'s Testing section as items are covered, following the plan-checklist skill's rules (verify before checking off, update immediately, don't batch).
+
+## 5. Minimum coverage bar
+
+At minimum, cover:
+- The happy path implied by the SRS's success criteria.
+- The edge cases that came up during the Phase 1 interview — those were flagged for a reason.

package/skills/plan-checklist/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: plan-checklist
+description: >-
+  Generates and religiously enforces a single consolidated plan-and-checklist
+  markdown file for a feature that already has an approved SRS. Use this
+  skill immediately after an SRS/requirements document is approved, to turn
+  it into a concrete, ordered, checkable task list. Then use this skill
+  again constantly during development — at the start of every coding turn
+  on that feature, before marking any task complete, whenever asked to
+  check progress or status, and whenever about to write code for a feature
+  that has a plan.md file. This is a persistent discipline skill, not a
+  one-time step. Consult and update the plan file on every development
+  turn for a tracked feature, even for changes that feel too small to
+  bother logging. Also trigger when the user says things like "what's
+  next", "where are we", "mark that done", "let's continue building", or
+  references a plan or checklist by name.
+---
+
+# Plan + checklist
+
+One markdown file per feature that is simultaneously the plan (ordered, concrete steps) and the checklist (checkboxes on those same steps) for everything left to do after the SRS is approved: the rest of Development, all of Testing, and all of Documentation.
+
+This skill is the enforcement layer between "we agreed what to build" (SRS) and "we're actually building it correctly, in order, without drifting." Its whole value is being consulted constantly, not written once and forgotten.
+
+## Relationship to the implementation-workflow skill
+
+If the `implementation-workflow` skill is present, this skill is what its Development, Testing, and Documentation phases read and update instead of a separate checklist file. If it isn't present, this skill still works standalone against any approved SRS-like document, or even a short informal goal description — see "Standalone use" below.
+
+## File location
+
+`docs/srs/<feature-slug>/plan.md`, next to that feature's `srs.md`. Same `<feature-slug>` the SRS uses.
+
+## 1. Creating the file (triggers once per feature, right after SRS approval)
+
+1. Read the approved `srs.md` in full — summary, requirements by phase, non-goals, risks.
+2. Turn each phase's requirements into concrete, individually-checkable tasks — finer-grained than the SRS bullets. A good task is small enough that "done" is unambiguous. Keep tasks in the order they should actually be built, respecting real dependencies.
+3. Append a **Testing** section and a **Documentation** section at the end, covering the rest of the parent workflow (test tasks per the SRS's success criteria and edge cases; the final feature-doc tasks).
+4. Write the file using `assets/plan-template.md` as the structure.
+5. Show the plan to the developer before starting work — not a full re-interview like the SRS phase, just a quick sanity check: "Here's the build order — look right?" Adjust if they push back, then proceed.
+
+## 2. Enforcing the file (triggers on every development turn after that)
+
+These rules are the actual point of this skill:
+
+- **Read `plan.md` before starting any development work**, every time — even if you read it earlier in this same conversation. It may have changed, especially across sessions or if it was edited outside the conversation.
+- **Work in the order the plan lists.** Don't jump to a later unchecked item because it's more interesting or seems faster, unless the plan itself is wrong (see deviations below).
+- **Never check off a task without verifying it.** "Wrote the function" is not done if it doesn't run; "wrote the test" is not done if it doesn't pass. No rubber-stamping.
+- **Update the file immediately after finishing a task** — check the box, update the `Last updated` line. Don't batch updates for later; batching is exactly how the file goes stale and stops being trustworthy.
+- **State which task you're on at the start of a work turn** — one short line, e.g. "Working on 2.3: wire up notification preferences API" — so the developer can redirect before deep work happens on the wrong thing.
+- **If you're about to write code that isn't tied to any unchecked plan item**, stop. Either the plan is stale and needs a quick update, or this is scope creep — surface it rather than doing invisible off-plan work.
+- **If the developer asks to skip a step or do something not on the plan**, don't silently comply. Ask whether to add it to the plan or treat it as a deliberate one-off, and record whichever it is.
+
+Use `scripts/check_plan_status.sh <path-to-plan.md>` for a fast, deterministic read of where things stand (counts of done/remaining, next unchecked task) instead of re-parsing the whole file by eye every time — cheaper and won't miscount.
+
+## 3. Deviations
+
+If actual work ends up diverging from the plan — a task turns out to be unnecessary, a new one is needed, the order had to change — don't silently edit the plan as if it always said that. Add a dated entry to the file's **Deviation log** section with what changed and why, then update the task list to match.
+
+## Standalone use (no SRS present)
+
+If this skill is triggered without an `implementation-workflow` SRS to draw from, ask the developer for a short goal description and a rough sense of scope, then build the plan directly from that conversation instead of from `srs.md`. Everything else — enforcement, deviations, status script — works the same.

package/skills/plan-checklist/assets/plan-template.md

@@ -0,0 +1,37 @@
+# <Feature title> — Plan & checklist
+
+**SRS:** [./srs.md](./srs.md)
+**Created:** <YYYY-MM-DD>
+**Status:** Not started | In progress | Blocked | Complete
+**Last updated:** <YYYY-MM-DD> — <what changed>
+
+## How to use this file
+
+Read this before starting any development work on this feature. Work top to bottom, in order. Check a box only once the task is actually verified done. Update "Last updated" immediately after every change — don't batch. Log any deviation from this plan in the Deviation log below rather than silently editing it away.
+
+## Plan
+
+### Phase 1: <name>
+
+- [ ] 1.1 <concrete, verifiable task>
+  - Notes: <implementation details decided along the way, if any>
+- [ ] 1.2 <task>
+
+### Phase 2: <name>
+
+- [ ] 2.1 <task>
+
+<add more phase headings to match srs.md>
+
+### Testing
+
+- [ ] T.1 <test task, derived from SRS success criteria / edge cases>
+
+### Documentation
+
+- [ ] D.1 Write `docs/features/<date>-<slug>.md`
+- [ ] D.2 Cross-link the feature doc from `srs.md`
+
+## Deviation log
+
+<dated entries — what changed from the original plan, and why>

package/skills/plan-checklist/scripts/check_plan_status.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# Fast, deterministic status snapshot of a plan.md file, so the agent doesn't
+# have to re-read and manually recount checkboxes on every single turn.
+#
+# Usage: scripts/check_plan_status.sh <path-to-plan.md>
+# If no path is given, searches docs/srs/*/plan.md and reports on each found.
+
+set -uo pipefail
+
+report_one() {
+  local file="$1"
+  if [ ! -f "$file" ]; then
+    echo "Not found: $file"
+    return 1
+  fi
+
+  local total done_count next_line next_phase last_updated
+  total=$(grep -Ec '^\s*-\s*\[[ xX]\]' "$file")
+  done_count=$(grep -Ec '^\s*-\s*\[[xX]\]' "$file")
+  local remaining=$((total - done_count))
+  local pct=0
+  if [ "$total" -gt 0 ]; then
+    pct=$(( done_count * 100 / total ))
+  fi
+
+  echo "=== $file ==="
+  last_updated=$(grep -m1 '^\*\*Last updated:\*\*' "$file" || echo "no Last updated line found")
+  echo "$last_updated"
+  echo "Progress: $done_count/$total done ($pct%), $remaining remaining"
+
+  # Find the current phase heading and first unchecked task under it.
+  next_line=$(grep -nE '^\s*-\s*\[\s\]' "$file" | head -1)
+  if [ -z "$next_line" ]; then
+    echo "Next task: none — all checked off."
+  else
+    local lineno taskline
+    lineno=$(echo "$next_line" | cut -d: -f1)
+    taskline=$(echo "$next_line" | cut -d: -f2-)
+    next_phase=$(awk -v ln="$lineno" 'NR < ln && /^### / { h=$0 } NR==ln { print h }' "$file")
+    echo "Current phase: ${next_phase:-unknown}"
+    echo "Next task:$taskline"
+  fi
+  echo
+}
+
+if [ $# -ge 1 ]; then
+  report_one "$1"
+else
+  found=0
+  while IFS= read -r f; do
+    found=1
+    report_one "$f"
+  done < <(find . -path '*/docs/srs/*/plan.md' 2>/dev/null)
+  if [ "$found" -eq 0 ]; then
+    echo "No plan.md files found under docs/srs/*/. Pass a path explicitly."
+    exit 1
+  fi
+fi