@syntesseraai/opencode-feature-factory 0.10.5 → 0.10.7

package/AGENTS.md

@@ -0,0 +1,37 @@
+# Feature Factory AGENTS Guide
+
+This file is installed to `~/.config/opencode/AGENTS.md` by `@syntesseraai/opencode-feature-factory`.
+
+## What Feature Factory Provides
+
+- Workflow tools:
+  - `ff_pipeline`: full multi-model planning/build/review/documentation workflow.
+  - `ff_mini_loop`: lightweight build/review/documentation loop for focused changes.
+  - `ff_list_models`: list available provider/model IDs for workflow overrides.
+- Specialized agents: `feature-factory`, `planning`, `building`, `reviewing`, `documenting`, and `ff-research`.
+- Skills for planning, review quality/security/architecture/documentation, reporting templates, and todo management.
+
+## Preferred Workflow Pattern
+
+1. Clarify requirements and acceptance criteria before coding.
+2. Choose `ff_mini_loop` for small, well-scoped changes.
+3. Choose `ff_pipeline` for complex, high-risk, or architectural changes.
+4. Confirm model overrides only when needed; otherwise use defaults.
+5. Use worktree isolation when running concurrent workflows.
+
+## Preferred Tooling Pattern
+
+- Use `cocoindex-code_search` first for semantic codebase discovery.
+- Use `read`, `glob`, and `grep` for targeted file inspection.
+- Use `morph-mcp_edit_file` for precise code/document edits.
+- Use `bash` for non-interactive command execution (`git`, `npm`, `tsc`, tests, builds).
+- Use PTY only when interactive terminal control is actually required.
+- Use `todowrite` for multi-step tasks to keep progress visible.
+
+## Implementation Expectations
+
+- Keep edits scoped and consistent with existing architecture.
+- Prefer non-destructive merges and preserve user configuration.
+- Update docs when behavior, defaults, or operational steps change.
+- Run relevant validation for touched areas (lint/typecheck/tests as needed).
+- Avoid destructive git operations unless explicitly requested.

package/README.md

@@ -23,16 +23,21 @@ The installer deploys to `~/.config/opencode/`:
 
 - `agents/`
 - `skills/`
+- `AGENTS.md`
 
 It also updates `~/.config/opencode/opencode.json` non-destructively by merging missing Feature Factory MCP entries and plugins without deleting existing user configuration.
 
 ## Install Behavior
 
-- **Always overwrites packaged assets**: installer unconditionally overwrites Feature Factory `agents` and `skills` files on every install.
+- **Always overwrites packaged assets**: installer unconditionally overwrites Feature Factory `agents`, `skills`, and `AGENTS.md` files on every install.
 - **`opencode.json` is non-destructive**: existing keys/values are preserved; only missing required plugin/MCP entries are added.
 - **No automatic plugin removals**: existing plugin entries are preserved as-is, including entries no longer in current defaults.
 - **Global scope**: assets are installed to `~/.config/opencode/` and shared across projects.
 
+## Global AGENTS Guide
+
+`~/.config/opencode/AGENTS.md` is installed from this package and provides Feature Factory-specific operating guidance, including workflow selection and preferred tool patterns (semantic search, edit workflow, and `bash`-first command execution).
+
 ## Tools
 
 The plugin exposes three MCP tools via the `feature-factory` agent:

package/bin/ff-deploy.js

@@ -3,7 +3,8 @@
 /**
  * Feature Factory Deployment Script
  *
- * Deploys skills and agents to the global OpenCode configuration directory.
+ * Deploys skills, agents, and AGENTS.md guidance to the global OpenCode
+ * configuration directory.
  * Run manually with: npx @syntesseraai/opencode-feature-factory
  */
 
@@ -19,10 +20,12 @@ const GLOBAL_CONFIG_DIR = join(homedir(), '.config', 'opencode');
 const SKILLS_DIR = join(GLOBAL_CONFIG_DIR, 'skills');
 const AGENTS_DIR = join(GLOBAL_CONFIG_DIR, 'agents');
 const GLOBAL_CONFIG_FILE = join(GLOBAL_CONFIG_DIR, 'opencode.json');
+const GLOBAL_AGENTS_GUIDE_FILE = join(GLOBAL_CONFIG_DIR, 'AGENTS.md');
 
 const PACKAGE_ROOT = join(__dirname, '..');
 const SOURCE_SKILLS_DIR = join(PACKAGE_ROOT, 'skills');
 const SOURCE_AGENTS_DIR = join(PACKAGE_ROOT, 'agents');
+const SOURCE_AGENTS_GUIDE_FILE = join(PACKAGE_ROOT, 'AGENTS.md');
 
 // Check if running in interactive mode (has TTY)
 const isInteractive = process.stdin.isTTY && process.stdout.isTTY;
@@ -135,6 +138,15 @@ async function getFileNames(dir) {
   }
 }
 
+async function fileExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 async function updateMCPConfig() {
   if (isInteractive) {
     console.log('\n🔧 MCP Configuration Update');
@@ -279,6 +291,7 @@ async function deploy() {
     // Get existing skills/agents for reporting
     const existingSkills = await getDirectoryNames(SKILLS_DIR);
     const existingAgents = await getFileNames(AGENTS_DIR);
+    const hadExistingAgentsGuide = await fileExists(GLOBAL_AGENTS_GUIDE_FILE);
 
     // Deploy skills
     if (isInteractive) {
@@ -315,11 +328,19 @@ async function deploy() {
       }
     }
 
+    // Deploy global AGENTS guide
+    await fs.copyFile(SOURCE_AGENTS_GUIDE_FILE, GLOBAL_AGENTS_GUIDE_FILE);
+    if (isInteractive) {
+      console.log('\n📘 Deploying AGENTS Guide...');
+      console.log(`  ${hadExistingAgentsGuide ? '🔄' : '✅'} AGENTS.md ${hadExistingAgentsGuide ? '(updated)' : '(new)'}`);
+    }
+
     // Summary
     if (isInteractive) {
       console.log('\n✨ Deployment Complete!');
       console.log(`   Skills: ${skills.length} deployed`);
       console.log(`   Agents: ${agents.length} deployed`);
+      console.log('   AGENTS guide: deployed');
       console.log(`   Location: ${GLOBAL_CONFIG_DIR}`);
       console.log('\n📝 Next Steps:');
       console.log('   - Restart OpenCode or run /reload to load new agents');

package/dist/tools/mini-loop.js

@@ -9,15 +9,40 @@
  * to the parent session via `promptAsync(noReply: true)`.
  */
 import { tool } from '@opencode-ai/plugin/tool';
+import { randomUUID } from 'node:crypto';
 import { promptSession, notifyParent, evaluateMiniLoopImplGate, evaluateMiniLoopDocGate, parseModelString, } from '../workflow/orchestrator.js';
-import { miniBuildPrompt, miniReviewPrompt, documentPrompt, docReviewPrompt, ciFixPrompt, } from './prompts.js';
-import { parseMiniReview, parseDocReview } from './parsers.js';
+import { miniBuildPrompt, miniReviewPrompt, documentPrompt, docReviewPrompt, ciFixPrompt, runNamePrompt, actionFirstReworkPrompt, } from './prompts.js';
+import { parseMiniReview, parseDocReview, parseImplementationReport, formatImplementationReportForHandoff } from './parsers.js';
 import { ciScriptExists, runCI } from '../workflow/ci-runner.js';
 import { cleanupWorktree, resolveRunDirectory } from '../workflow/run-isolation.js';
 // ---------------------------------------------------------------------------
 // Tool factory
 // ---------------------------------------------------------------------------
 const formatElapsed = (startMs, endMs) => `${((endMs - startMs) / 1000).toFixed(1)}s`;
+const normalizeRunName = (raw, fallback) => {
+    const normalized = raw
+        .trim()
+        .replace(/^[-#*\s]+/, '')
+        .replace(/\s+/g, ' ')
+        .slice(0, 80);
+    return normalized.length > 0 ? normalized : fallback;
+};
+const asBulletList = (items, empty) => {
+    if (items.length === 0) {
+        return `- ${empty}`;
+    }
+    return items.map((item) => `- ${item}`).join('\n');
+};
+const formatStructuredStage = (stage, includeActionItems) => {
+    const base = `STATUS: ${stage.status}\n` +
+        `SUMMARY: ${stage.summary}\n` +
+        `CHECKLIST:\n${asBulletList(stage.checklist, 'No checklist provided.')}\n` +
+        `ISSUES:\n${asBulletList(stage.issues, 'No issues reported.')}`;
+    if (!includeActionItems) {
+        return base;
+    }
+    return `${base}\nACTION_ITEMS:\n${asBulletList(stage.actionItems, 'No action items required.')}`;
+};
 export function createMiniLoopTool(client) {
     return tool({
         description: 'Run the Feature Factory mini-loop: build → review (with rework loop) → documentation. ' +
@@ -56,6 +81,8 @@ export function createMiniLoopTool(client) {
             const callerSessionId = context.sessionID;
             const agent = context.agent;
             const { requirements } = args;
+            const runId = randomUUID();
+            let runName = normalizeRunName(requirements.split('\n')[0] || '', 'Mini-Loop Workflow');
             // Resolve models — use provided overrides or undefined (inherit session model)
             const buildModel = args.build_model
                 ? parseModelString(args.build_model)
@@ -79,6 +106,18 @@ export function createMiniLoopTool(client) {
                 sessionId: callerSessionId,
                 directory: runDirectoryContext.runDirectory,
             };
+            try {
+                const runNameRaw = await promptSession(client, runContext, runNamePrompt('Mini-Loop', requirements), {
+                    model: buildModel,
+                    agent: 'building',
+                    title: 'ff-mini-run-name',
+                });
+                runName = normalizeRunName(runNameRaw, runName);
+            }
+            catch {
+                // Keep fallback name derived from requirements when name generation fails.
+            }
+            const runHeader = `Mini-Loop: ${runName} (${runId})`;
             // Fire-and-forget: run orchestration in background
             let lastPhase = 'init';
             const asyncOrchestration = async () => {
@@ -89,7 +128,7 @@ export function createMiniLoopTool(client) {
                         report.push(`## ${phase}\n${msg}`);
                     };
                     // Notify helper bound to this session
-                    const notify = (message, options) => notifyParent(client, runContext, agent, message, options);
+                    const notify = (message, options) => notifyParent(client, runContext, agent, `# ${runHeader}\n\n${message}`, options);
                     // ===================================================================
                     // PHASE 1: IMPLEMENTATION LOOP (build → review → gate, up to 10)
                     // ===================================================================
@@ -98,6 +137,8 @@ export function createMiniLoopTool(client) {
                     const implementationIterationDetails = [];
                     let implGate = { decision: 'REWORK', feedback: requirements };
                     let lastImplRaw = '';
+                    let lastImplementationHandoff = '';
+                    let nextImplementationDirective;
                     // Phase start notification
                     await notify(`# Mini-Loop: Building started\n\nStarting implementation phase...\n`);
                     for (let implIter = 0; implIter < 10 && implGate.decision === 'REWORK'; implIter++) {
@@ -106,7 +147,7 @@ export function createMiniLoopTool(client) {
                         const reviewTitle = `ff-mini-review-${iteration}`;
                         const buildInput = implIter === 0
                             ? requirements
-                            : `${requirements}\n\nPrevious review feedback:\n${implGate.feedback}`;
+                            : `${requirements}\n\nPrevious implementation handoff for context:\n${lastImplementationHandoff || lastImplRaw}`;
                         context.metadata({
                             title: `⏳ Building (iteration ${iteration}/10)...`,
                             metadata: {
@@ -118,7 +159,7 @@ export function createMiniLoopTool(client) {
                         });
                         // Build
                         const buildStartMs = Date.now();
-                        lastImplRaw = await promptSession(client, runContext, miniBuildPrompt(buildInput, implIter > 0 ? implGate.feedback : undefined), { model: buildModel, agent: 'building', title: buildTitle });
+                        lastImplRaw = await promptSession(client, runContext, miniBuildPrompt(buildInput, nextImplementationDirective), { model: buildModel, agent: 'building', title: buildTitle });
                         const buildEndMs = Date.now();
                         // ---------------------------------------------------------------
                         // CI validation (deterministic subprocess — not an LLM prompt)
@@ -141,14 +182,32 @@ export function createMiniLoopTool(client) {
                                         maxCiAttempts,
                                     },
                                 });
-                                await notify(`# Mini-Loop: CI validation — attempt ${ciAttempt}/${maxCiAttempts}\n`);
                                 const ciResult = await runCI(ciDir);
                                 if (ciResult.passed) {
-                                    await notify(`# Mini-Loop: CI passed (attempt ${ciAttempt}/${maxCiAttempts})\n`);
+                                    const ciStageOutput = {
+                                        status: 'APPROVED',
+                                        summary: `CI validation passed on attempt ${ciAttempt}/${maxCiAttempts}.`,
+                                        checklist: ['ff-ci.sh executed in run directory', 'No failing lint/typecheck/test/build checks'],
+                                        issues: [],
+                                        actionItems: [],
+                                        raw: 'CI passed',
+                                    };
+                                    await notify(`Stage: CI Validation — attempt ${ciAttempt}/${maxCiAttempts}\n` +
+                                        `${formatStructuredStage(ciStageOutput, false)}`);
                                     break;
                                 }
                                 // CI failed
-                                await notify(`# Mini-Loop: CI failed (attempt ${ciAttempt}/${maxCiAttempts})\n\n\`\`\`\n${ciResult.output}\n\`\`\`\n`);
+                                const ciFailureStage = {
+                                    status: 'REWORK',
+                                    summary: `CI failed on attempt ${ciAttempt}/${maxCiAttempts}.`,
+                                    checklist: ['ff-ci.sh executed in run directory'],
+                                    issues: ['CI reported failing checks.'],
+                                    actionItems: ['Fix CI failures before continuing to the next attempt.'],
+                                    raw: ciResult.output,
+                                };
+                                await notify(`Stage: CI Validation — attempt ${ciAttempt}/${maxCiAttempts}\n` +
+                                    `${formatStructuredStage(ciFailureStage, true)}\n\n` +
+                                    `\`\`\`\n${ciResult.output}\n\`\`\`\n`);
                                 if (ciAttempt < maxCiAttempts) {
                                     // Ask build model to fix the CI failures
                                     context.metadata({
@@ -187,6 +246,20 @@ export function createMiniLoopTool(client) {
                                 }
                             }
                         }
+                        const implementation = parseImplementationReport(lastImplRaw);
+                        const implementationHandoff = formatImplementationReportForHandoff(implementation);
+                        lastImplementationHandoff = implementationHandoff;
+                        const buildStageOutput = {
+                            ...implementation.stageOutput,
+                            status: implementation.stageOutput.status ||
+                                (implementation.testsPassed && implementation.openIssues.length === 0
+                                    ? 'APPROVED'
+                                    : 'REWORK_REQUIRED'),
+                        };
+                        await notify(`Stage: Build Output — iteration ${iteration}/10\n` +
+                            `${formatStructuredStage(buildStageOutput, buildStageOutput.actionItems.length > 0)}\n` +
+                            `Files Changed: ${implementation.filesChanged.length}\n` +
+                            `Tests Passed: ${implementation.testsPassed}`);
                         context.metadata({
                             title: `⏳ Reviewing (iteration ${iteration}/10)...`,
                             metadata: {
@@ -198,7 +271,7 @@ export function createMiniLoopTool(client) {
                         });
                         // Review
                         const reviewStartMs = Date.now();
-                        const reviewRaw = await promptSession(client, runContext, miniReviewPrompt(lastImplRaw), {
+                        const reviewRaw = await promptSession(client, runContext, miniReviewPrompt(implementationHandoff), {
                             model: reviewModel,
                             agent: 'reviewing',
                             title: reviewTitle,
@@ -207,6 +280,15 @@ export function createMiniLoopTool(client) {
                         const review = parseMiniReview(reviewRaw);
                         // Gate (deterministic)
                         implGate = evaluateMiniLoopImplGate(review, iteration);
+                        if (implGate.decision === 'REWORK') {
+                            nextImplementationDirective = actionFirstReworkPrompt({
+                                ...review.stageOutput,
+                                status: implGate.decision,
+                            }, `${requirements}\n\nPrevious implementation handoff for context:\n${implementationHandoff}\n\nReview feedback:\n${implGate.feedback || review.reworkInstructions || review.raw}`, implGate.feedback || review.reworkInstructions || review.raw);
+                        }
+                        else {
+                            nextImplementationDirective = undefined;
+                        }
                         if (implGate.decision === 'APPROVED') {
                             context.metadata({
                                 title: `✅ Implementation APPROVED (confidence: ${review.confidence}, iteration: ${iteration})`,
@@ -246,14 +328,21 @@ export function createMiniLoopTool(client) {
                                 },
                             });
                         }
-                        const feedback = review.reworkInstructions || implGate.feedback || review.raw;
+                        const implementationStageOutput = {
+                            ...review.stageOutput,
+                            status: implGate.decision,
+                        };
                         implementationIterationDetails.push(`### Iteration ${iteration}\n` +
                             `- **Build**: ${buildTitle} (${formatElapsed(buildStartMs, buildEndMs)})\n` +
                             `- **Review**: ${reviewTitle} (${formatElapsed(reviewStartMs, reviewEndMs)})\n` +
                             `- **Gate**: ${implGate.decision} (confidence: ${review.confidence}, change requested: ${review.changeRequested ? 'yes' : 'no'}, unresolved: ${review.unresolvedIssues})\n` +
-                            `- **Feedback**: ${feedback}`);
+                            `${formatStructuredStage(implementationStageOutput, implGate.decision === 'REWORK')}`);
                         // Notify each implementation iteration gate decision
-                        await notify(`# Mini-Loop: Building — Iteration ${iteration}/10\n\nStatus: ${implGate.decision}\nConfidence: ${review.confidence}%\nUnresolved Issues: ${review.unresolvedIssues}\nDuration: ${formatElapsed(implementationStartMs, Date.now())}\nFeedback: ${feedback}\n`);
+                        await notify(`Stage: Building — iteration ${iteration}/10\n` +
+                            `${formatStructuredStage(implementationStageOutput, implGate.decision === 'REWORK')}\n` +
+                            `Confidence: ${review.confidence}%\n` +
+                            `Unresolved Issues: ${review.unresolvedIssues}\n` +
+                            `Duration: ${formatElapsed(implementationStartMs, Date.now())}`);
                         if (implGate.decision === 'ESCALATE') {
                             const implementationEndMs = Date.now();
                             addReport('Implementation', `${implementationIterationDetails.join('\n\n')}\n\n**Outcome**: ESCALATE: ${implGate.reason}\n**Phase time**: ${formatElapsed(implementationStartMs, implementationEndMs)}`);
@@ -298,7 +387,7 @@ export function createMiniLoopTool(client) {
                     lastPhase = 'Documentation';
                     const documentationStartMs = Date.now();
                     const documentationIterationDetails = [];
-                    let docInput = lastImplRaw;
+                    let docInput = lastImplementationHandoff || lastImplRaw;
                     let docGate = { decision: 'REWORK' };
                     // Phase start notification
                     await notify(`# Mini-Loop: Documentation started\n\nStarting documentation phase...\n`);
@@ -382,16 +471,26 @@ export function createMiniLoopTool(client) {
                                 },
                             });
                         }
-                        const feedback = docReview.reworkInstructions || docGate.feedback || docReview.raw;
+                        const docStageOutput = {
+                            ...docReview.stageOutput,
+                            status: docGate.decision,
+                        };
                         documentationIterationDetails.push(`### Iteration ${iteration}\n` +
                             `- **Write**: ${writeTitle} (${formatElapsed(writeStartMs, writeEndMs)})\n` +
                             `- **Review**: ${reviewTitle} (${formatElapsed(reviewStartMs, reviewEndMs)})\n` +
                             `- **Gate**: ${docGate.decision} (confidence: ${docReview.confidence}, unresolved: ${docReview.unresolvedIssues})\n` +
-                            `- **Feedback**: ${feedback}`);
+                            `${formatStructuredStage(docStageOutput, docGate.decision === 'REWORK')}`);
                         // Notify each documentation iteration gate decision
-                        await notify(`# Mini-Loop: Documentation — Iteration ${iteration}/5\n\nStatus: ${docGate.decision}\nConfidence: ${docReview.confidence}%\nUnresolved Issues: ${docReview.unresolvedIssues}\nDuration: ${formatElapsed(documentationStartMs, Date.now())}\nFeedback: ${feedback}\n`);
+                        await notify(`Stage: Documentation — iteration ${iteration}/5\n` +
+                            `${formatStructuredStage(docStageOutput, docGate.decision === 'REWORK')}\n` +
+                            `Confidence: ${docReview.confidence}%\n` +
+                            `Unresolved Issues: ${docReview.unresolvedIssues}\n` +
+                            `Duration: ${formatElapsed(documentationStartMs, Date.now())}`);
                         if (docGate.decision === 'REWORK') {
-                            docInput = `${docInput}\n\nDocumentation review feedback:\n${docGate.feedback}`;
+                            docInput = actionFirstReworkPrompt({
+                                ...docReview.stageOutput,
+                                status: docGate.decision,
+                            }, `${docInput}\n\nDocumentation review feedback:\n${docGate.feedback || docReview.reworkInstructions || docReview.raw}`, docGate.feedback || docReview.reworkInstructions || docReview.raw);
                         }
                     }
                     const documentationEndMs = Date.now();
@@ -425,11 +524,11 @@ export function createMiniLoopTool(client) {
             // Launch orchestration in background — fire-and-forget
             void asyncOrchestration().catch(async (err) => {
                 const message = err instanceof Error ? err.message : String(err);
-                await notifyParent(client, runContext, agent, `# Mini-Loop: Error\n\nPhase: ${lastPhase}\nError: ${message}\n`, { noReply: false });
+                await notifyParent(client, runContext, agent, `# Mini-Loop: ${runName} (${runId})\n\nStage: Error\nSTATUS: FAILED\nSUMMARY: Workflow terminated during ${lastPhase}.\nCHECKLIST:\n- Captured terminal error\nISSUES:\n- ${message}\n`, { noReply: false });
             });
             // Return immediately with acknowledgment
             const summary = requirements.length > 120 ? requirements.slice(0, 120) + '...' : requirements;
-            return `Mini-loop started for: ${summary}\n\nRun directory: ${runDirectoryContext.runDirectory}\nWorktree isolation: ${runDirectoryContext.worktreeEnabled ? 'enabled' : 'disabled'}\nYou will receive progress updates as each phase completes.`;
+            return `Mini-loop started for: ${summary}\n\nRun: ${runName} (${runId})\nRun directory: ${runDirectoryContext.runDirectory}\nWorktree isolation: ${runDirectoryContext.worktreeEnabled ? 'enabled' : 'disabled'}\nYou will receive progress updates as each phase completes.`;
         },
     });
 }

package/dist/tools/parsers.d.ts

@@ -5,13 +5,15 @@
  * structured sections cannot be found. The gate evaluators work on
  * the parsed numbers/booleans, not on freeform text.
  */
-import type { PlanProposal, ConsensusPlan, ReviewReport, ReviewSynthesis, DocReview, ImplementationReport, DocUpdate } from '../workflow/types.js';
+import type { PlanProposal, ConsensusPlan, ReviewReport, ReviewSynthesis, DocReview, ImplementationReport, DocUpdate, StageOutput, MiniLoopReview } from '../workflow/types.js';
 /** Extract the first integer found after a label in the text. */
 export declare function extractNumber(text: string, label: string, fallback?: number): number;
 /** Extract text between two section headers (markdown-style). */
 export declare function extractSection(text: string, heading: string): string;
 /** Check if a YES/NO field is YES. */
 export declare function isYes(text: string, label: string): boolean;
+export declare function parseStageOutput(raw: string, defaults?: Partial<Pick<StageOutput, 'status' | 'summary'>>): StageOutput;
+export declare function formatActionItems(actionItems: string[]): string;
 export declare function parsePlanProposal(tag: string, raw: string): PlanProposal;
 export declare function parseConsensusPlan(raw: string): ConsensusPlan;
 export declare function parseReviewReport(tag: string, raw: string): ReviewReport;
@@ -19,10 +21,5 @@ export declare function parseReviewSynthesis(raw: string): ReviewSynthesis;
 export declare function parseDocUpdate(raw: string): DocUpdate;
 export declare function parseDocReview(raw: string): DocReview;
 export declare function parseImplementationReport(raw: string): ImplementationReport;
-export declare function parseMiniReview(raw: string): {
-    confidence: number;
-    changeRequested: boolean;
-    unresolvedIssues: number;
-    reworkInstructions?: string;
-    raw: string;
-};
+export declare function formatImplementationReportForHandoff(report: ImplementationReport): string;
+export declare function parseMiniReview(raw: string): MiniLoopReview;