knoxis-helper 1.7.2 → 1.8.2

package/bin/knoxis-helper.js

@@ -397,7 +397,7 @@ async function main() {
     console.log(`knoxis-helper@${pkgVersion}`);
     if (fw) {
       console.log(`framework bundle: v${fw.bundle}`);
-      console.log(`  kickoff v${fw.documents.kickoff}, resume v${fw.documents.resume}, session-end v${fw.documents.sessionEnd}, recovery v${fw.documents.recovery}, ruleset v${fw.documents.codingRuleset}, portal-contract v${fw.documents.portalContract}`);
+      console.log(`  kickoff v${fw.documents.kickoff}, feature-kickoff v${fw.documents.featureKickoff}, resume v${fw.documents.resume}, session-end v${fw.documents.sessionEnd}, recovery v${fw.documents.recovery}, ruleset v${fw.documents.codingRuleset}, portal-contract v${fw.documents.portalContract}`);
     }
     process.exit(0);
   }

package/lib/framework-version.js

@@ -12,10 +12,11 @@
 // "what methodology version is baked into it." Both ride together in every
 // session record so the portal can render them.
 module.exports = {
-  bundle: '1.1.0',
+  bundle: '1.2.0',
   documents: {
     overview: 1,
     kickoff: 8,
+    featureKickoff: 1,
     resume: 4,
     sessionEnd: 4,
     recovery: 3,

package/lib/knoxis-interactive-pair.js

@@ -367,13 +367,19 @@ async function runKitMode(kitMode, task, identity, scaffoldResult) {
   const pattern = process.env.KNOXIS_KIT_PATTERN || null;
   let tpl;
   try {
+    // feature-kickoff additionally consumes identity (userId, workspaceId,
+    // parent task) so the manifest can carry portal linkage. The other kit
+    // templates ignore unknown fields, so passing them through is safe.
     tpl = kitTemplates.getTemplate(kitMode, {
       taskDescription: task || null,
       archetype,
       pattern,
       productSlug: identity.productSlug,
       projectSlug: identity.projectSlug,
-      workspace: identity.workspace
+      workspace: identity.workspace,
+      userId: identity.userId,
+      workspaceId: identity.workspaceId,
+      parentTaskId: (identity.taskIds && identity.taskIds.length) ? identity.taskIds[0] : null
     });
   } catch (e) {
     console.error('Kit template error: ' + e.message);

package/lib/knoxis-local-agent.js

@@ -594,14 +594,15 @@ function resolvePairProgramScript() {
   return null;
 }
 
-const KIT_MODES = new Set(['kickoff', 'resume', 'session-end', 'recovery']);
-// kickoff and resume rely on Claude actually writing files to disk
-// (docs/state/OPEN_QUESTIONS.md and the rest of the context pack). The
-// interactive runner invokes `claude -p --session-id`, which gives Claude
-// proper tool access; pair-program.js pipes to `claude` without -p and
-// silently skips the file writes. Route those two kits through the
-// interactive runner so their kit prompts actually do their work.
-const KIT_MODES_VIA_INTERACTIVE = new Set(['kickoff', 'resume']);
+const KIT_MODES = new Set(['kickoff', 'feature-kickoff', 'resume', 'session-end', 'recovery']);
+// Every kit mode rewrites files on disk — STATUS / HANDOFF / DECISIONS for
+// session-end, the docs/state/* + docs/features/<slug>/* bag for kickoff /
+// feature-kickoff / resume, and recovery's triage notes. The interactive
+// runner invokes `claude -p --session-id`, which gives Claude proper tool
+// access; the older pair-program.js pipes to `claude` without -p and silently
+// skips the file writes. Route every kit mode through the interactive runner
+// so their kit prompts actually do their work.
+const KIT_MODES_VIA_INTERACTIVE = new Set(['kickoff', 'feature-kickoff', 'resume', 'session-end', 'recovery']);
 
 function buildPairProgramCommand({ scriptPath, workspace, mode, archetype, pattern, productSlug, projectSlug, taskPrompt, userId, workspaceId, taskIds }) {
   const q = v => `"${escapeForDoubleQuotedShellArg(v)}"`;

package/lib/session-recorder.js

@@ -34,39 +34,106 @@ function extractFilesTouched(diff) {
   return Array.from(seen);
 }
 
-// Snapshot the 6 well-known state files (docs/state/*.md) so the
-// session record carries the latest STATUS / HANDOFF / DECISIONS / etc.
-// up to the portal for display on qig.ai.
+// Snapshot the canonical state files so the session record carries the
+// latest STATUS / HANDOFF / DECISIONS / etc. up to the portal for display
+// on qig.ai. Three groups are captured into a single bag keyed by relative
+// path; the frontend distinguishes them by path prefix.
+//
+//   docs/state/*.md            — project-level state (always present after scaffold)
+//   docs/architecture/*.md     — ARCHITECTURE.md + ADRs from project-kickoff
+//   docs/features/<slug>/*     — per-feature ROADMAP / PHASES / STATUS / manifest
+//                                from feature-kickoff (one entry per feature)
+//
+// All three flow through `stateFiles` on the session record. The Java
+// PairProgrammerSessionService persists the bag to the `state_files` JSONB
+// column; no schema change is needed to add new path prefixes.
 const STATE_FILES_TO_CAPTURE = [
   'docs/state/STATUS.md',
   'docs/state/HANDOFF.md',
   'docs/state/DECISIONS.md',
   'docs/state/CHANGELOG.md',
   'docs/state/OPEN_QUESTIONS.md',
-  'docs/state/RISKS.md'
+  'docs/state/RISKS.md',
+  // Project architecture pack from kickoff v7.
+  'docs/architecture/ARCHITECTURE.md'
+];
+const FEATURE_FILE_NAMES = [
+  'ROADMAP.md',
+  'PHASES.md',
+  'STATUS.md',
+  'OPEN_QUESTIONS.md',
+  'manifest.json'
 ];
 const MAX_STATE_FILE_BYTES = 256 * 1024; // 256KB per file
 
+function readSafe(absPath, relPath, out) {
+  try {
+    const stat = fs.statSync(absPath);
+    if (!stat.isFile()) return;
+    if (stat.size > MAX_STATE_FILE_BYTES) {
+      out[relPath] = `[File omitted: ${stat.size} bytes exceeds ${MAX_STATE_FILE_BYTES}-byte cap]`;
+      return;
+    }
+    out[relPath] = fs.readFileSync(absPath, 'utf8');
+  } catch (e) {
+    // Missing file is normal — skip silently.
+  }
+}
+
 function readStateFiles(workspace) {
   const out = {};
   if (!workspace) return out;
+
+  // Fixed list (state pack + ARCHITECTURE).
   for (const rel of STATE_FILES_TO_CAPTURE) {
-    const abs = path.join(workspace, rel);
-    try {
-      const stat = fs.statSync(abs);
-      if (!stat.isFile()) continue;
-      if (stat.size > MAX_STATE_FILE_BYTES) {
-        out[rel] = `[File omitted: ${stat.size} bytes exceeds ${MAX_STATE_FILE_BYTES}-byte cap]`;
-        continue;
+    readSafe(path.join(workspace, rel), rel, out);
+  }
+
+  // ADRs — docs/architecture/adr/*.md.
+  const adrDir = path.join(workspace, 'docs', 'architecture', 'adr');
+  try {
+    for (const entry of fs.readdirSync(adrDir, { withFileTypes: true })) {
+      if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+      const rel = `docs/architecture/adr/${entry.name}`;
+      readSafe(path.join(adrDir, entry.name), rel, out);
+    }
+  } catch (e) {
+    // No ADR dir is normal.
+  }
+
+  // Per-feature files — docs/features/<slug>/{ROADMAP,PHASES,STATUS,OPEN_QUESTIONS}.md
+  // and manifest.json. One slug = one folder.
+  const featuresDir = path.join(workspace, 'docs', 'features');
+  try {
+    for (const entry of fs.readdirSync(featuresDir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      for (const filename of FEATURE_FILE_NAMES) {
+        const rel = `docs/features/${entry.name}/${filename}`;
+        readSafe(path.join(featuresDir, entry.name, filename), rel, out);
       }
-      out[rel] = fs.readFileSync(abs, 'utf8');
-    } catch (e) {
-      // Missing file is normal — skip silently.
     }
+  } catch (e) {
+    // No features dir is normal.
   }
+
   return out;
 }
 
+// Enumerate feature slugs from the workspace so the frontend can list features
+// without parsing the bag. Returns sorted array of slug strings.
+function listFeatureSlugs(workspace) {
+  if (!workspace) return [];
+  const featuresDir = path.join(workspace, 'docs', 'features');
+  try {
+    return fs.readdirSync(featuresDir, { withFileTypes: true })
+      .filter(e => e.isDirectory())
+      .map(e => e.name)
+      .sort();
+  } catch (e) {
+    return [];
+  }
+}
+
 // Snapshot product.local.json from the project's parent directory (per
 // kickoff v7 Phase -1) so the session record carries product context up to
 // the portal. Multiple projects under one product share this file; the
@@ -270,10 +337,16 @@ class SessionRecorder {
       completedSteps,
       closedCleanly,
       filesTouched: extractFilesTouched(totalDiff),
-      // Snapshot of docs/state/*.md at session-end so the QIG frontend can
-      // display the latest STATUS / HANDOFF / DECISIONS / etc. without
-      // needing live filesystem access on the dev's machine.
+      // Snapshot of state-pack + architecture + feature files at session-end
+      // so the QIG frontend can display the latest STATUS / HANDOFF /
+      // DECISIONS / ROADMAP / etc. without needing live filesystem access
+      // on the dev's machine. Single bag keyed by relative path; frontend
+      // filters by prefix (docs/state/*, docs/architecture/*,
+      // docs/features/<slug>/*).
       stateFiles: readStateFiles(this.workspace),
+      // Quick index of feature slugs found in docs/features/. Lets the
+      // frontend enumerate features without parsing the bag.
+      featureSlugs: listFeatureSlugs(this.workspace),
       // Snapshot of product.local.json from the parent directory so the
       // frontend can render product context alongside the session record.
       productContext: readProductContext(this.workspace),
@@ -299,5 +372,6 @@ module.exports = {
   slugify,
   extractFilesTouched,
   readStateFiles,
-  readProductContext
+  readProductContext,
+  listFeatureSlugs
 };

package/lib/templates/feature-kickoff.js

@@ -0,0 +1,327 @@
+'use strict';
+
+// Feature Kickoff — single-shot, autonomous (v1)
+//
+// Where project-kickoff sets up a brand-new project context pack, feature-kickoff
+// takes a single feature task from the operator, decomposes it into a phased
+// roadmap, and writes the roadmap + phase plan + machine-readable manifest into
+// docs/features/<slug>/. Multiple features can coexist; each is independently
+// trackable from the QIG dashboard via its manifest.json.
+//
+// State machine (similar shape to resume.js, autonomous-first):
+//   A: docs/features/<slug>/ missing                        → write the roadmap
+//   B: directory exists with unanswered _(fill in)_ entries → wait
+//   C: directory exists, no pending answers                 → refresh in place
+
+const FEATURE_KICKOFF_BODY = `# Feature Kickoff (single-shot, autonomous)
+
+You are running in single-shot mode. You produce one response and the process
+exits. Your job is to take the operator's feature description (the task in the
+session header above), decompose it into a concrete phased roadmap, and write
+the roadmap + phase plan + manifest to disk so the QIG dashboard can track it.
+
+This is **planning only** — you do not change application code in this run.
+
+## Step 0 — Orient on the project
+
+Read these files first (whichever exist) to ground your plan in the codebase:
+
+- \`CLAUDE.md\`
+- \`README.md\`
+- \`docs/state/STATUS.md\`
+- \`docs/state/HANDOFF.md\`
+- \`docs/state/DECISIONS.md\`
+- \`docs/architecture/ARCHITECTURE.md\` (if present)
+- Any entry-point files mentioned in CLAUDE.md
+
+If the project has none of this, still proceed — feature-kickoff does not
+require project-kickoff to have run first.
+
+## Step 1 — Pick a feature slug
+
+Derive a slug from the feature description in the session header. Lowercase,
+dashes, ≤40 chars, semantically descriptive. Examples:
+
+- "Add real-time notification toasts" → \`realtime-notification-toasts\`
+- "Replace polling with SSE on the dashboard" → \`dashboard-sse-replacement\`
+
+Do not include the words "feature" or "task" in the slug.
+
+## Step 2 — State-branch detection
+
+Check \`docs/features/<slug>/\`:
+
+- **State A — directory missing.** First run for this feature. Continue to Step 3.
+- **State B — directory exists and \`docs/features/<slug>/OPEN_QUESTIONS.md\` has at least one entry under \`## Pending Answers\` whose \`**Answer:**\` line is still \`_(fill in)_\`.** Print:
+
+\`\`\`
+Feature kickoff blocked — waiting on answers in docs/features/<slug>/OPEN_QUESTIONS.md.
+
+Unanswered: #<n>, #<n>
+Answered:   #<n>
+
+Fill in the remaining **Answer:** lines and re-run feature-kickoff.
+\`\`\`
+
+Then stop. Do not edit the roadmap or phase files.
+
+- **State C — directory exists, no pending answers (refresh).** Re-read the
+existing roadmap and phases. Reconcile with the operator's note in the session
+header (if it adds new scope or corrects something), then update files in place.
+Skip to Step 4.
+
+## Step 3 — Decompose the feature into phases
+
+Plan 3–6 phases. Each phase has 2–6 concrete steps. Phases run sequentially.
+Each phase must have a clear "done" definition.
+
+Default phase shape (adjust per feature; collapse to 2–3 phases if small,
+expand if large):
+
+1. **Discovery** — read existing code, find integration points, list
+constraints
+2. **Design** — data model / API contract / UI shape decisions; capture in
+DECISIONS where non-trivial
+3. **Implementation** — break into commit-sized steps; each step touches
+named files
+4. **Testing** — unit / integration / manual coverage
+5. **Rollout** — feature flag, docs, telemetry, deprecations
+
+Each step is one imperative-voice action plus the file(s) or surface it
+touches. Steps must be small enough to ship in one pair-program session.
+
+**Don't pad.** A 4-step feature is fine. A 30-step feature with 3 phases of
+filler is not.
+
+## Step 4 — Capture genuine open questions only
+
+If something truly cannot be decided autonomously (missing API decision,
+ambiguous scope, conflicting existing patterns), append it to
+\`docs/features/<slug>/OPEN_QUESTIONS.md\` under \`## Pending Answers\` using
+this shape:
+
+\`\`\`markdown
+### N. <question>
+*Phase: <phase number>. Raised: <today's ISO date>.*
+**Answer:** _(fill in)_
+\`\`\`
+
+**Be sparing.** Most "questions" are decisions you should make and capture in
+the feature's DECISIONS section. If you write more than 3 pending questions
+you are over-using this.
+
+If you write any pending questions, you are now in a partial State A — write
+OPEN_QUESTIONS.md, write a stub manifest.json with \`"status": "blocked"\` at
+the feature level, do NOT write ROADMAP.md / PHASES.md / STATUS.md, and stop
+with a short note pointing the operator at OPEN_QUESTIONS.md. The next run
+(after answers are filled) will pick up at State C and write the rest.
+
+## Step 5 — Write files
+
+All paths are relative to the workspace root. Create \`docs/features/<slug>/\`
+if missing.
+
+### \`docs/features/<slug>/ROADMAP.md\`
+
+\`\`\`markdown
+---
+feature_slug: <slug>
+feature_title: <descriptive title>
+parent_task_id: <from session header; null if not provided>
+workspace_id: <from session header; null if not provided>
+user_id: <from session header; null if not provided>
+created_at: <ISO date>
+status: planning
+---
+
+# Feature Roadmap: <title>
+
+## Summary
+<2–3 sentence summary of what this feature does and why it matters>
+
+## Phases
+1. **<Phase 1 title>** — <one-line goal>
+2. **<Phase 2 title>** — <one-line goal>
+...
+
+## Definition of done
+- <criterion>
+- <criterion>
+
+## Notes
+<anything important the operator should know — risks, constraints,
+discovered-during-planning facts. "None." if none.>
+\`\`\`
+
+### \`docs/features/<slug>/PHASES.md\`
+
+\`\`\`markdown
+---
+feature_slug: <slug>
+---
+
+# <title> — Phases
+
+## Phase 1: <title>
+**Goal:** <one sentence>
+**Done when:** <crisp criterion>
+
+- [ ] 1.1 — <action>  *(touches: <file or surface>)*
+- [ ] 1.2 — ...
+
+## Phase 2: <title>
+**Goal:** ...
+**Done when:** ...
+
+- [ ] 2.1 — ...
+...
+\`\`\`
+
+### \`docs/features/<slug>/STATUS.md\`
+
+\`\`\`markdown
+---
+feature_slug: <slug>
+---
+
+# <title> — Status
+
+_Last updated: <ISO date>_
+_Current phase: 1_
+
+## Progress
+- [ ] Phase 1: <title>
+- [ ] Phase 2: <title>
+...
+
+## Active step
+None yet — kicked off, awaiting first work session.
+
+## Recent activity
+- <ISO date>: feature kicked off
+
+## Notes
+None.
+\`\`\`
+
+### \`docs/features/<slug>/manifest.json\`
+
+\`\`\`json
+{
+  "feature_slug": "<slug>",
+  "feature_title": "<title>",
+  "parent_task_id": "<id or null>",
+  "workspace_id": "<id or null>",
+  "user_id": "<id or null>",
+  "product_slug": "<from session header or null>",
+  "project_slug": "<from session header or null>",
+  "kicked_off_at": "<ISO timestamp>",
+  "status": "planning",
+  "current_phase": "phase-1",
+  "phases": [
+    {
+      "id": "phase-1",
+      "title": "<title>",
+      "goal": "<goal>",
+      "done_when": "<criterion>",
+      "status": "pending",
+      "steps": [
+        {
+          "id": "phase-1-step-1",
+          "action": "<imperative action>",
+          "touches": "<file or surface>",
+          "status": "pending"
+        }
+      ]
+    }
+  ],
+  "definition_of_done": ["<criterion>", "<criterion>"]
+}
+\`\`\`
+
+The \`manifest.json\` is the canonical machine-readable form. The MD files are
+the human-readable view. Keep them consistent — if you change a phase title or
+step in one, change it in all four files.
+
+## Step 6 — Append to project state (don't overwrite)
+
+Touch two project-level files. **Append only — do not overwrite other
+sections.**
+
+\`docs/state/STATUS.md\` — under \`## Notes\` (create the section if missing),
+append:
+
+> Feature kicked off: \`<slug>\` — see \`docs/features/<slug>/\`.
+
+\`docs/state/CHANGELOG.md\` — under \`## [Unreleased]\` → \`### Added\`,
+append a single bullet:
+
+> Feature roadmap: \`<slug>\` (kickoff <date>).
+
+Do not touch \`docs/state/HANDOFF.md\`, \`docs/state/DECISIONS.md\`,
+\`docs/state/OPEN_QUESTIONS.md\`, or any application code. Feature
+kickoff is planning only.
+
+## Step 7 — Output for the operator
+
+End your response with a copyable block summarizing what was written:
+
+\`\`\`
+Feature kickoff complete: <slug>
+
+Files:
+  docs/features/<slug>/ROADMAP.md
+  docs/features/<slug>/PHASES.md
+  docs/features/<slug>/STATUS.md
+  docs/features/<slug>/manifest.json
+
+Project state:
+  docs/state/STATUS.md (appended Notes entry)
+  docs/state/CHANGELOG.md (appended Added entry)
+
+Next: pick a step from PHASES.md and start a normal pair-program session on it.
+The dashboard will track progress against manifest.json.
+\`\`\`
+
+## Non-negotiables
+
+- Write files. Do not describe what you would write.
+- Use the operator's task description as the feature description verbatim
+where reasonable; only paraphrase to fit slug/title/summary length.
+- Keep \`manifest.json\` consistent with the three MD files at all times.
+- One feature per run. The slug picked in Step 1 is final for this run.
+- Do not modify project code. Planning only.
+- Never overwrite an existing \`docs/features/<slug>/ROADMAP.md\` outside
+State C. If State A detection misfires (directory exists but you think it
+shouldn't), halt with a one-line note rather than clobbering.
+
+---
+
+`;
+
+function buildFeatureKickoffPrompt({
+  taskDescription,
+  productSlug,
+  projectSlug,
+  workspace,
+  userId,
+  workspaceId,
+  parentTaskId
+} = {}) {
+  const header = ['Mode: feature-kickoff'];
+  if (productSlug) header.push(`Product: ${productSlug}`);
+  if (projectSlug) header.push(`Project: ${projectSlug}`);
+  if (workspace) header.push(`Workspace: ${workspace}`);
+  if (userId) header.push(`User ID: ${userId}`);
+  if (workspaceId) header.push(`Workspace ID: ${workspaceId}`);
+  if (parentTaskId) header.push(`Parent task ID: ${parentTaskId}`);
+  if (taskDescription) header.push(`Feature description (use as-is for the title and summary):\n${taskDescription}`);
+  const ctx = `Session context:\n${header.join('\n')}\n\n`;
+  return ctx + FEATURE_KICKOFF_BODY;
+}
+
+module.exports = {
+  title: 'Feature Kickoff',
+  body: FEATURE_KICKOFF_BODY,
+  buildPrompt: buildFeatureKickoffPrompt
+};

package/lib/templates/index.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const kickoff = require('./kickoff');
+const featureKickoff = require('./feature-kickoff');
 const resume = require('./resume');
 const sessionEnd = require('./session-end');
 const recovery = require('./recovery');
@@ -8,6 +9,7 @@ const codingRuleset = require('./coding-ruleset');
 
 const MODES = {
   kickoff,
+  'feature-kickoff': featureKickoff,
   resume,
   'session-end': sessionEnd,
   recovery

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "knoxis-helper",
-  "version": "1.7.2",
+  "version": "1.8.2",
   "description": "Local helper for Knoxis pair programming - connects your machine to Knoxis on qig.ai",
   "bin": {
     "knoxis-helper": "./bin/knoxis-helper.js"