@yarkingulacti/agentic-scaffold 0.6.0 → 0.7.0

package/README.md

@@ -60,7 +60,7 @@ npx @yarkingulacti/agentic-scaffold --interactive
 npx @yarkingulacti/agentic-scaffold --target ../my-project
 
 # Skip specific groups
-npx @yarkingulacti/agentic-scaffold --skip-skills --skip-scripts
+npx @yarkingulacti/agentic-scaffold --skip-skills --skip-scripts --skip-hooks
 
 # Pre-configure values
 npx @yarkingulacti/agentic-scaffold --project-name "my-app" --issue-tracker github
@@ -87,7 +87,8 @@ project/
 │   │   └── glossary.md       # Ubiquitous language glossary
 │   ├── engineering/README.md
 │   └── product/README.md
-├── .agents/skills/           # Agent skill definitions (20 skills)
+├── .agents/skills/           # Agent skill definitions (21 skills)
+├── .agents/hooks/            # Pre/post lifecycle hooks for agent workflows
 ├── scripts/                  # Markdown memory indexing pipeline
 ├── .scratchpad/              # Local detailed planning
 └── .history/                 # Shipped work summaries
@@ -115,7 +116,15 @@ CLI flags.
 |-------|-------------|------|
 | `docs` | Documentation framework (CODING_PRINCIPLES, ADR, agents, context) | `--skip-docs` |
 | `scripts` | Python memory indexing pipeline (sqlite-vec based RAG) | `--skip-scripts` |
-| `skills` | 20 agent skills (implement, bugfix, diagnose, tdd, fill-docs, etc.) | `--skip-skills` |
+| `skills` | 21 agent skills (implement, bugfix, create-hook, diagnose, tdd, fill-docs, etc.) | `--skip-skills` |
+| `hooks` | Pre/post lifecycle hooks for agent workflows (pre-feature, post-feature, post-bugfix, post-session) with executable scripts | `--skip-hooks` |
+
+## New in v0.7
+
+- **Agent lifecycle hooks** — new `.agents/hooks/` component group with 4 hooks (pre-feature, post-feature, post-bugfix, post-session) and executable shell scripts. Skills reference hooks conditionally with graceful fallback.
+- **`create-hook` skill** — new agent skill that guides you through adding custom hooks for any lifecycle point.
+- **`--skip-hooks` flag** — skip the hooks component group.
+- **98 tests** — detection, scaffolding, CLI, and hooks tested end-to-end.
 
 ## New in v0.5
 

package/bin/index.js

@@ -35,11 +35,14 @@ const argv = yargs(hideBin(process.argv))
     description: "Comma-separated component groups to include: docs,scripts,skills,all",
     default: "all",
   })
-  .option("skip-skills", {
-    type: "boolean",
-    description: "Skip skill files",
-    default: false,
-  })
+      .option("skip-skills", {
+        type: "boolean",
+        description: "Skip agent skill definitions",
+      })
+      .option("skip-hooks", {
+        type: "boolean",
+        description: "Skip agent lifecycle hook templates",
+      })
   .option("skip-scripts", {
     type: "boolean",
     description: "Skip memory scripts",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yarkingulacti/agentic-scaffold",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Scaffold agentic development documentation & configuration into any project",
   "type": "module",
   "bin": {
@@ -15,7 +15,9 @@
   ],
   "scripts": {
     "test": "node --test tests/*.test.js",
-    "prepublishOnly": "npm test"
+    "prepublishOnly": "npm test",
+    "release": "commit-and-tag-version",
+    "release:dry": "commit-and-tag-version --dry-run"
   },
   "dependencies": {
     "handlebars": "^4.7.8",
@@ -29,5 +31,8 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/yarkingulacti/agentic-scaffold.git"
+  },
+  "devDependencies": {
+    "commit-and-tag-version": "^12.7.3"
   }
 }

package/src/prompts.js

@@ -36,10 +36,10 @@ export async function askOverwrite(filePath) {
 export async function askComponents() {
   const r = rl();
   console.log("\nComponent groups to include (comma-separated):");
-  console.log("  docs, scripts, skills");
+  console.log("  docs, scripts, skills, hooks");
   const answer = await r.question("All [default]: ");
   r.close();
   const trimmed = answer.trim().toLowerCase();
-  if (!trimmed) return ["docs", "scripts", "skills"];
+  if (!trimmed) return ["docs", "scripts", "skills", "hooks"];
   return trimmed.split(",").map((s) => s.trim()).filter(Boolean);
 }

package/src/scaffold.js

@@ -43,10 +43,11 @@ function resolveIncludes(argv) {
   if (argv.only && argv.only !== "all") {
     return new Set(argv.only.split(",").map((s) => s.trim()));
   }
-  const set = new Set(["docs", "scripts", "skills"]);
+  const set = new Set(["docs", "scripts", "skills", "hooks"]);
   if (argv.skipDocs) set.delete("docs");
   if (argv.skipScripts) set.delete("scripts");
   if (argv.skipSkills) set.delete("skills");
+  if (argv.skipHooks) set.delete("hooks");
   return set;
 }
 
@@ -239,6 +240,12 @@ async function scaffoldSkills(config, extraOpts = {}) {
   return copyStaticDir(skillsSrc, skillsDest, { force: config.force, interactive: config.interactive, ...extraOpts });
 }
 
+async function scaffoldHooks(config, hbData, extraOpts = {}) {
+  const hooksSrc = join(TEMPLATES_DIR, "hooks");
+  const hooksDest = join(config.target, ".agents", "hooks");
+  return renderDir(hooksSrc, hooksDest, hbData, { force: config.force, interactive: config.interactive, ...extraOpts });
+}
+
 async function scaffoldScratchpad(config, extraOpts = {}) {
   const src = join(TEMPLATES_DIR, "scratchpad");
   const dest = join(config.target, ".scratchpad");
@@ -257,6 +264,7 @@ function countTemplateFiles(config) {
     ...(config.include.has("docs") ? [join(TEMPLATES_DIR, "docs")] : []),
     ...(config.include.has("scripts") ? [join(TEMPLATES_DIR, "scripts")] : []),
     ...(config.include.has("skills") ? [join(TEMPLATES_DIR, "skills")] : []),
+    ...(config.include.has("hooks") ? [join(TEMPLATES_DIR, "hooks")] : []),
     join(TEMPLATES_DIR, "scratchpad"),
     join(TEMPLATES_DIR, "history"),
   ];
@@ -311,6 +319,7 @@ export async function scaffold(argv) {
   if (config.include.has("docs")) results.push(...(await scaffoldDocs(config, hbData, tickOpts)));
   if (config.include.has("scripts")) results.push(...(await scaffoldScripts(config, hbData, tickOpts)));
   if (config.include.has("skills")) results.push(...(await scaffoldSkills(config, tickOpts)));
+  if (config.include.has("hooks")) results.push(...(await scaffoldHooks(config, hbData, tickOpts)));
 
   results.push(...(await scaffoldScratchpad(config, tickOpts)));
   results.push(...(await scaffoldHistory(config, tickOpts)));

package/templates/docs/agents/session-close.md.hbs

@@ -5,6 +5,11 @@ handing off.
 
 ## Required Steps
 
+If `.agents/hooks/post-session.md` exists, read and follow it instead of this
+file — it contains the canonical post-session workflow.
+
+Otherwise, follow the steps below:
+
 1. Run the relevant tests.
 2. Build every touched project when a build command exists.
 3. Create or update `.history/DD.MM.YYYY/README.md` with the master work title,

package/templates/hooks/post-bugfix.md.hbs

@@ -0,0 +1,17 @@
+# Post-Bugfix Hook
+
+Fires after a bugfix is delivered.
+
+## Steps
+
+1. Run the project's test suite to confirm the fix does not regress:
+   {{#if packageManager}}   `{{packageManager}} test`{{else}}   `npm test`{{/if}}
+2. Run `.agents/hooks/scripts/post-bugfix.sh` if it exists.
+3. Update `.history/DD.MM.YYYY/README.md` with a summary of the fix.
+4. Update the related `.scratchpad/` status to mark completion.
+5. Create a Conventional Commit under the master work title.
+
+## When to skip
+
+If the project has no tests or no history directory, skip the unavailable
+steps silently. Do not pretend they succeeded.

package/templates/hooks/post-feature.md.hbs

@@ -0,0 +1,18 @@
+# Post-Feature Hook
+
+Fires after a feature is delivered by any implementation skill.
+
+## Steps
+
+1. Run the project's test suite:
+   {{#if packageManager}}   `{{packageManager}} test`{{else}}   `npm test`{{/if}}
+2. Run `.agents/hooks/scripts/post-feature.sh` if it exists.
+3. Update `.history/DD.MM.YYYY/README.md` with a summary of shipped work.
+4. Run `scripts/memory_index.py` to keep the vector index current.
+5. Update the related `.scratchpad/` status to mark completion.
+6. Create a Conventional Commit under the master work title.
+
+## When to skip
+
+If the project has no tests, no history directory, or no memory pipeline,
+skip the unavailable steps silently. Do not pretend they succeeded.

package/templates/hooks/post-session.md.hbs

@@ -0,0 +1,34 @@
+# Post-Session Hook
+
+Fires after every successful coding session, regardless of the skill used.
+Replaces the legacy session-close workflow.
+
+## Steps
+
+1. Run `.agents/hooks/scripts/post-session.sh` if it exists.
+2. Run all applicable post-* hooks that match the work done:
+   - After feature work: `.agents/hooks/post-feature.md`
+   - After bugfix work: `.agents/hooks/post-bugfix.md`
+3. Build every touched project when a build command exists.
+4. Run `scripts/memory_index.py` so `.history/` is in the vector database.
+5. Update all affected `.scratchpad/` status lines.
+6. Push the feature/bugfix branch to the remote.
+7. Create a PR, review it, merge it, then delete the PR branch.
+
+## Commit Message Format
+
+Use the master work title as the first line, then the Conventional Commit:
+
+```
+<Master work title>
+
+<type>(<scope>): <short imperative summary>
+```
+
+Allowed types: `feat`, `fix`, `docs`, `refactor`, `test`, `build`, `ci`, `chore`.
+
+## Blockers
+
+If a step cannot run because the repo has no command, no remote, invalid
+auth, or missing external service, record that in `.history/` and the final
+response. Do not pretend the step succeeded.

package/templates/hooks/pre-feature.md.hbs

@@ -0,0 +1,17 @@
+# Pre-Feature Hook
+
+Fires before a feature implementation begins, regardless of which skill
+initiates the work.
+
+## Steps
+
+1. Read `BUSINESS_LOGIC.md` and any relevant ADR.
+2. Read the issue ticket and matching `.scratchpad/` detail file.
+3. If no scratchpad detail exists and the task is complex, create one.
+4. Read `docs/CODING_PRINCIPLES.md` to confirm approach.
+5. Run `.agents/hooks/scripts/pre-feature.sh` if it exists.
+
+## When to skip
+
+If any referenced file does not exist, proceed silently — do not flag the
+absence unless the task specifically requires it.

package/templates/hooks/scripts/post-bugfix.sh.hbs

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# Post-bugfix hook — runs after a bugfix is delivered.
+# Customize this file with project-specific post-fix tasks.
+#
+# Available context variables:
+#   projectName    = "{{projectName}}"
+#   packageManager = "{{packageManager}}"
+#   scriptLanguage = "{{scriptLanguage}}"
+
+set -euo pipefail
+
+echo "Running post-bugfix checks for {{projectName}}..."
+{{#if packageManager}}
+{{packageManager}} run lint 2>/dev/null || true
+{{/if}}

package/templates/hooks/scripts/post-feature.sh.hbs

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# Post-feature hook — runs after a feature is delivered.
+# Customize this file with project-specific post-delivery tasks.
+#
+# Available context variables:
+#   projectName    = "{{projectName}}"
+#   packageManager = "{{packageManager}}"
+#   scriptLanguage = "{{scriptLanguage}}"
+
+set -euo pipefail
+
+echo "Running post-feature tasks for {{projectName}}..."
+{{#if packageManager}}
+{{packageManager}} run lint 2>/dev/null || true
+{{/if}}

package/templates/hooks/scripts/post-session.sh.hbs

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# Post-session hook — runs after every successful coding session.
+# Customize this file with project-specific session-close tasks.
+#
+# Available context variables:
+#   projectName    = "{{projectName}}"
+#   packageManager = "{{packageManager}}"
+#   scriptLanguage = "{{scriptLanguage}}"
+
+set -euo pipefail
+
+echo "Running post-session tasks for {{projectName}}..."
+{{#if packageManager}}
+{{packageManager}} run build 2>/dev/null || true
+{{/if}}

package/templates/hooks/scripts/pre-feature.sh.hbs

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# Pre-feature hook — runs before feature implementation begins.
+# Customize this file with project-specific pre-flight checks.
+#
+# Available context variables:
+#   projectName    = "{{projectName}}"
+#   packageManager = "{{packageManager}}"
+#   scriptLanguage = "{{scriptLanguage}}"
+
+set -euo pipefail
+
+echo "Running pre-feature checks for {{projectName}}..."
+{{#if packageManager}}
+echo "  Package manager: {{packageManager}}"
+{{/if}}

package/templates/root/AGENTS.md.hbs

@@ -22,6 +22,18 @@ Shipped work is summarized in `.history/DD.MM.YYYY/README.md`. Use separated
 dated worklog files only; do not use issue comments as the project memory.
 After every successful coding session, follow `docs/agents/session-close.md`.
 
+### Agent lifecycle hooks
+
+Pre/post lifecycle hooks live in `.agents/hooks/`. Implementation skills
+reference them automatically. Available hooks:
+
+- `.agents/hooks/pre-feature.md` — before implementing a feature
+- `.agents/hooks/post-feature.md` — after implementing a feature
+- `.agents/hooks/post-bugfix.md` — after fixing a bug
+- `.agents/hooks/post-session.md` — after a coding session (canonical
+  post-session workflow, replaces `docs/agents/session-close.md`)
+- `.agents/hooks/scripts/` — executable helpers for the hooks above
+
 ### Domain docs
 
 Use `BUSINESS_LOGIC.md`, `docs/`, and `docs/adr/` as tracked source material.

package/templates/root/CLAUDE.md.hbs

@@ -22,6 +22,18 @@ Shipped work is summarized in `.history/DD.MM.YYYY/README.md`. Use separated
 dated worklog files only; do not use issue comments as the project memory.
 After every successful coding session, follow `docs/agents/session-close.md`.
 
+### Agent lifecycle hooks
+
+Pre/post lifecycle hooks live in `.agents/hooks/`. Implementation skills
+reference them automatically. Available hooks:
+
+- `.agents/hooks/pre-feature.md` — before implementing a feature
+- `.agents/hooks/post-feature.md` — after implementing a feature
+- `.agents/hooks/post-bugfix.md` — after fixing a bug
+- `.agents/hooks/post-session.md` — after a coding session (canonical
+  post-session workflow, replaces `docs/agents/session-close.md`)
+- `.agents/hooks/scripts/` — executable helpers for the hooks above
+
 ### Domain docs
 
 Use `BUSINESS_LOGIC.md`, `docs/`, and `docs/adr/` as tracked source material.

package/templates/skills/bugfix/SKILL.md

@@ -9,4 +9,5 @@ Diagnose and fix a described bug.
 3. Identify the smallest root-cause fix.
 4. Add or update a regression test when practical.
 5. Run focused verification.
-6. Record shipped work in `.history/DD.MM.YYYY/README.md` when the fix ships.
+6. If `.agents/hooks/post-bugfix.md` exists, read and follow it.
+   Otherwise record shipped work in `.history/DD.MM.YYYY/README.md`.

package/templates/skills/create-hook/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: create-hook
+description: >
+  Interview the user to identify a new lifecycle hook point, then create the
+  hook markdown file, optional executable script, and wire it into the
+  relevant skills.
+---
+
+# Create Hook
+
+Add a new agent lifecycle hook to `.agents/hooks/`. Hooks are markdown files
+that describe what an AI agent should do at a specific point in the workflow
+(pre-feature, post-bugfix, etc.).
+
+## Steps
+
+### 1. Determine the hook point
+
+Ask the user what event should trigger the hook. Common patterns:
+
+| Prefix | Meaning | Example |
+|--------|---------|---------|
+| `pre-` | Before an event | `pre-deploy`, `pre-commit`, `pre-test` |
+| `post-` | After an event | `post-deploy`, `post-migration`, `post-docs-change` |
+
+If the user is unsure, suggest hooking into `post-session.md` instead — it
+already chains to `post-feature.md` and `post-bugfix.md`.
+
+### 2. Name and create the hook file
+
+Name the file `<prefix>-<name>.md` and create it at `.agents/hooks/`. Use
+this anatomy:
+
+```markdown
+# <Name> Hook
+
+Fires <when this hook runs, e.g. "after every database migration">.
+
+## Steps
+
+1. First step the agent should take.
+2. Second step.
+3. Run `.agents/hooks/scripts/<name>.sh` if it exists.
+
+## When to skip
+
+Conditions under which the agent should silently skip this hook.
+```
+
+### 3. Create the optional executable script
+
+If the hook needs automation, create `.agents/hooks/scripts/<name>.sh`:
+
+```bash
+#!/usr/bin/env bash
+# <Name> hook — runs <when>.
+set -euo pipefail
+```
+
+Follow the project's script language convention. Make the script
+idempotent where possible.
+
+### 4. Wire into skills
+
+Add a conditional reference in every skill where the hook should fire.
+Use the existing pattern:
+
+```markdown
+4. If `.agents/hooks/<hook-name>.md` exists, read and follow it.
+```
+
+Skills commonly wired to hooks:
+
+| Skill | Hook point | File |
+|-------|-----------|------|
+| `implement` | pre + post | `.agents/skills/implement/SKILL.md` |
+| `bugfix` | post | `.agents/skills/bugfix/SKILL.md` |
+| `tdd` | pre + post | `.agents/skills/tdd/SKILL.md` |
+
+### 5. Wire into the session close chain
+
+If the hook should fire at the end of every session, add it to the
+`post-session.md` chaining step — for example, after the existing
+sub-hook references.
+
+### 6. Confirm with the user
+
+Show the user:
+- The new hook file path
+- The script file path (if created)
+- Which skills reference it

package/templates/skills/implement/SKILL.md

@@ -6,10 +6,12 @@ when not in Plan Mode.
 ## Steps
 
 1. Read `BUSINESS_LOGIC.md` and relevant ADRs.
-2. Read the Linear issue and matching `.scratchpad/` detail file.
-3. If no scratchpad detail exists, create one before coding.
-4. Implement the smallest complete slice that satisfies the plan.
-5. Run focused verification.
-6. Record shipped work in `.history/DD.MM.YYYY/README.md`.
+2. If `.agents/hooks/pre-feature.md` exists, read and follow it.
+3. Read the Linear issue and matching `.scratchpad/` detail file.
+4. If no scratchpad detail exists, create one before coding.
+5. Implement the smallest complete slice that satisfies the plan.
+6. Run focused verification.
+7. If `.agents/hooks/post-feature.md` exists, read and follow it.
+   Otherwise record shipped work in `.history/DD.MM.YYYY/README.md`.
 
 Keep Linear descriptions short. Keep detailed reasoning in `.scratchpad/`.