claudify-agent 1.0.5 → 1.0.7

package/.claude/commands/backbone-init.md

@@ -0,0 +1,20 @@
+---
+description: Scan the project and draft BACKBONE.md (project map loaded every session)
+argument-hint: [extra notes about the project]
+---
+
+Draft or refresh `BACKBONE.md` at the project root. Notes from me: $ARGUMENTS
+
+1. Scan shallowly, do not read whole trees:
+   - manifests: package.json, go.mod, pyproject.toml, foundry.toml, Cargo.toml, docker/compose files;
+   - top-level dirs (and sub-repos if this is a multi-repo workspace);
+   - README, CLAUDE.md, `docs/` file names and first headings; `openspec/` or `spec/` if present;
+   - CI workflows for the real lint/test/build commands.
+2. Fill every section of the existing `BACKBONE.md` (or the template if missing):
+   - Docs index: one line per doc, with status. Mark a doc outdated only with evidence (superseded note, archive folder, version mismatch); otherwise ask.
+   - Capabilities: one line per `spec/specs/*.md` (or `openspec/specs/*/` if migrating from OpenSpec).
+   - Invariants: only rules found in docs or that I confirm. Never invent business rules.
+3. Keep it under ~80 lines. Link, never copy.
+4. List what you could not determine as questions, batched in one message.
+5. Set `Last synced: <HEAD short sha> (<date>)` so `/backbone-sync` can diff from here.
+6. Show the full diff and wait for my approval before writing.

package/.claude/commands/backbone-sync.md

@@ -0,0 +1,20 @@
+---
+description: Re-sync BACKBONE.md with the current source after work done without specs
+argument-hint: [area to focus on]
+---
+
+Sync `BACKBONE.md` with the code as it is now. Focus: $ARGUMENTS
+
+1. Find what changed since the last sync:
+   - read the `Last synced:` commit in `BACKBONE.md`; run `git log --stat <commit>..HEAD` (and `git status` for uncommitted work);
+   - no commit recorded → fall back to the shallow scan of `/backbone-init`.
+   Read only the changed files that matter (manifests, new dirs, new docs, CI, public APIs); not every diff line.
+2. Compare against `BACKBONE.md` section by section and list gaps:
+   - Structure: new / moved / removed modules or repos;
+   - Docs index: new docs, docs that now contradict the code (candidate outdated);
+   - Commands: scripts or CI steps that changed;
+   - Capabilities: behaviour that exists in code but has no `spec/specs/*.md` entry;
+   - Open changes: entries whose `spec/changes/*.md` is gone or done.
+3. Also compare with `spec/specs/*.md` for the touched areas. Report code that contradicts an archived requirement, but do not edit specs: that is my call (fix the code or open a change).
+4. Ask me about anything you cannot decide from evidence, batched in one message. Never invent invariants.
+5. Show the `BACKBONE.md` diff, including `Last synced: <HEAD short sha> (<date>)`, and wait for my approval before writing.

package/.claude/commands/learn.md

@@ -0,0 +1,17 @@
+---
+description: Turn a mistake I just corrected into a rule so it never repeats
+argument-hint: <what went wrong and what is right>
+---
+
+Lesson to learn: $ARGUMENTS
+
+If the argument is empty, infer the lesson from the correction I made earlier in this conversation.
+
+1. State the lesson as one imperative line: what to do (or never do) and when. Add a one-line why if not obvious.
+2. Pick where it belongs, most specific first:
+   - business invariant or project-wide fact (e.g. a doc is outdated) → Invariants or Docs index in `BACKBONE.md`;
+   - how specs should be written → `spec/config.md`;
+   - a technology or practice covered by a skill → that `.claude/skills/<name>/SKILL.md`, under a `## Lessons` section;
+   - general working style → `.claude/rules/lessons.md` (always loaded, keep it under 30 lines).
+3. Check the target for an existing rule that covers it; if so, sharpen that line instead of adding a duplicate.
+4. Show me the exact diff and wait for my approval before writing.

package/.claude/commands/spec-apply.md

@@ -0,0 +1,14 @@
+---
+description: Implement the next unchecked tasks of a spec change
+argument-hint: <change-name> [task number]
+---
+
+Implement spec change: $ARGUMENTS
+
+1. Read `spec/changes/<change-name>.md`; respect the Invariants in `BACKBONE.md`. Nothing else up front; read code only as each task needs it.
+2. Take the requested task, or the first unchecked `- [ ]` task. Work one task at a time.
+3. Implement it, then run its DoD. Fix until it passes (max 5 attempts, then stop and report).
+4. Tick it `- [x]` in the change file. If reality differs from the spec, update the spec (Requirements/Design) in the same step and tell me.
+5. Report in 2-3 lines: task done, proof run, next task. Continue to the next task only if I asked for more than one.
+
+When every task is ticked, set `Status: done` and suggest `/spec-archive <change-name>`.

package/.claude/commands/spec-archive.md

@@ -0,0 +1,15 @@
+---
+description: Merge a finished change's requirements into the spec backbone and archive it
+argument-hint: <change-name>
+---
+
+Archive spec change: $ARGUMENTS
+
+1. Read `spec/changes/<change-name>.md`. Refuse if any task is unchecked; list them.
+2. For each `### <capability>` block under Requirements, update `spec/specs/<capability>.md` (create if new):
+   - Keep only Requirements and Scenarios: the current truth of the system, no history, no tasks.
+   - ADDED → append. MODIFIED → replace the requirement of the same name in full. REMOVED → delete it.
+   - If a MODIFIED/REMOVED name does not exist in the backbone, stop and ask instead of guessing.
+3. Move the change file to `spec/changes/archive/YYYY-MM-DD-<change-name>.md`.
+4. Update `BACKBONE.md`: remove the change from "Open changes"; add or update the one-line entry under "Capabilities" for each capability touched.
+5. Show me the diff of `spec/specs/` in a short summary.

package/.claude/commands/spec-new.md

@@ -0,0 +1,40 @@
+---
+description: Draft a lightweight spec for a new feature (single file, ~800 words)
+argument-hint: <change-name> <what the feature should do>
+---
+
+Create a spec change for: $ARGUMENTS
+
+1. `BACKBONE.md` is already in context. Read `spec/config.md`, then only the `spec/specs/*.md` capabilities this feature touches and only the doc sections from the Docs index it needs.
+2. Ask me (one batched question) anything that changes scope. Do not guess scope.
+3. Write `spec/changes/<change-name>.md` with exactly these sections, following the rules in `spec/config.md`:
+
+```markdown
+# <change-name>
+Status: draft | Depends on: <change or none>
+
+## Why
+## Scope
+- In: ...
+- Out (non-goals): ...
+## Requirements
+<!-- One block per affected capability, named like spec/specs/<capability>.md -->
+### <capability> (new | modified)
+#### ADDED Requirement: <name>
+<statement with SHALL/MUST>
+- Scenario <name>: GIVEN ... WHEN ... THEN ...
+#### MODIFIED Requirement: <existing name>
+<full new text, not just the diff>
+#### REMOVED Requirement: <existing name>
+<reason>
+## Design
+<only decisions not obvious from the code: data flow, schema, API, edge cases. Omit section if trivial.>
+## Risks
+## Tasks
+- [ ] 1. <task> — files: ... — DoD: ...
+```
+
+4. Keep the whole file under ~800 words, plus ~300 per extra capability. No restating config, docs or code; link them.
+   If it still does not fit (e.g. more than 4 capabilities), propose splitting into smaller changes with `Depends on:` instead of one giant spec.
+5. Add the change as one line under "Open changes" in `BACKBONE.md`.
+6. Do not write code. Finish by showing the task list and asking me to approve before `/spec-apply`.

package/CLAUDE.md

@@ -4,6 +4,12 @@
 
 ---
 
+## 0. 🗺️ Project Backbone (always loaded)
+@BACKBONE.md
+
+If it still holds `<placeholders>`, suggest `/backbone-init`. Follow its Invariants on every task.
+If you finish work without a spec that changes structure, docs, commands or capabilities, suggest `/backbone-sync`.
+
 ## 1. 🛑 Context & Token Preservation (Sub-20 Line Core)
 - Keep responses concise and targeted. Never dump entire files when diffs suffice.
 - Do NOT read whole directory trees. Inspect shallow structure first.
@@ -20,6 +26,11 @@
   - Validation steps: `.claude/rules/plan-mode-validation.md`
   - Plan structure guide: `.claude/rules/plan-mode-structure.md`
 
+## 2b. 📐 Spec Workflow (features only, opt-in by command)
+- `/spec-new` → `/spec-apply` → `/spec-archive`. Specs live in `spec/` (config, changes, specs backbone).
+- Bugs and small tasks: no spec, work directly.
+- After the user corrects a mistake, suggest `/learn` so it never repeats.
+
 ## 3. 🧪 Zero-Token Local Verification Loop
 After modifying code, execute local verification based on project stack:
 - **Node/TS/NestJS:** `npm run lint:fix && npm run typecheck`

package/bin/cli.js

@@ -41,6 +41,21 @@ if (command === 'init') {
       console.log(`  ⚠️  Kept your existing .claude/settings.json — merge the "hooks" block from ${settingsSrc} manually.`);
     }
 
+    // 3. Scaffold BACKBONE.md and spec/ (never overwrite existing files)
+    const templates = [
+      ['BACKBONE.md', 'project map loaded every session; run /backbone-init to fill it'],
+      ['spec/config.md', 'rules for /spec-new'],
+    ];
+    for (const [file, purpose] of templates) {
+      const dest = join(targetDir, file);
+      if (existsSync(dest)) {
+        console.log(`  ⚠️  Kept your existing ${file}`);
+      } else {
+        await cp(join(packageRoot, 'templates', file), dest);
+        console.log(`  ✅ Created ${file} (${purpose})`);
+      }
+    }
+
     console.log('\n🎉 Successfully initialized Claudify!');
     console.log('👉 Next Steps:');
     console.log('   - Review CLAUDE.md in your project root.');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudify-agent",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "Enterprise-grade workflow & context optimization framework for Claude Code, Claude Desktop, and AI coding agents.",
   "repository": {
     "type": "git",
@@ -16,6 +16,7 @@
     "CLAUDE.md",
     ".claude",
     "bin",
+    "templates",
     "README.md",
     "package.json"
   ],

package/templates/BACKBONE.md

@@ -0,0 +1,40 @@
+# Project Backbone
+
+> Loaded every session. A map, not documentation: link to details, never copy them. Keep under ~80 lines.
+> Fill with `/backbone-init`; kept in sync by `/spec-new`, `/spec-archive` and `/learn`; after work done without specs, run `/backbone-sync`.
+
+Last synced: <commit> (<date>)
+
+## Overview
+- What: <one or two lines: what the system does and for whom>
+- Stack: <languages, frameworks, infra>
+
+## Structure
+| Path / repo | Role |
+|---|---|
+| <path> | <what lives there> |
+
+## Docs index
+| Doc | About | Status |
+|---|---|---|
+| <path> | <topic> | current / outdated (do not use for X) |
+
+## Capabilities
+<!-- One line per spec/specs/<capability>.md -->
+- <capability>: <one line>
+
+## Open changes
+<!-- One line per spec/changes/<name>.md not yet archived -->
+- none
+
+## Commands
+- Install: <cmd>
+- Verify (DoD default): <lint && typecheck && test>
+
+## Invariants
+<!-- Rules every change MUST respect. One line each. -->
+- <e.g. money amounts are integers in base units, never floats>
+
+## Conventions
+- Branch / commit: <e.g. feat/<topic> from develop, conventional commits>
+- Language & style: <e.g. Vietnamese prose, English technical terms>

package/templates/spec/config.md

@@ -0,0 +1,16 @@
+# Spec Config
+
+> Rules for writing spec changes, read by `/spec-new` only. Project context, invariants and commands live in `BACKBONE.md`.
+
+## Proposal
+- Must have Why, Scope (in / out = Non-goals), Depends on, Risks.
+- Reference docs by section instead of copying them.
+
+## Requirements
+- `#### ADDED|MODIFIED|REMOVED Requirement: <name>` containing SHALL or MUST.
+- Each has scenarios GIVEN / WHEN / THEN with concrete values: at least one happy path and one failure.
+
+## Tasks
+- Each task fits in 2-4 hours, lists files/packages touched and its DoD.
+- Tests ship with the task that adds the logic, not at the end.
+- DoD default: the Verify command in `BACKBONE.md`.