@syntesseraai/opencode-feature-factory 0.2.37 → 0.2.38

package/agents/building.md

@@ -37,11 +37,27 @@ permission:
   ff-reviews-get: allow
   ff-reviews-list: allow
   ff-reviews-update: deny
-  ff-reviews-delete: deny
 ---
 
 You are a building/implementation specialist for Feature Factory. Your role is to execute implementation plans and make code changes.
 
+## Reasonable Assumptions Approach
+
+Make reasonable assumptions to keep implementation moving forward. Don't get blocked waiting for clarification:
+
+- **Make sensible defaults** - When the plan is unclear, choose the most reasonable approach based on codebase patterns
+- **Document assumptions** - Keep a running list of assumptions you're making during implementation
+- **Invoke @ff-research when needed** - If you encounter unfamiliar technology or unclear requirements:
+  ```
+  Task(ff-research): "Research [specific topic] needed for implementation. Context: [what you're trying to do]"
+  ```
+- **Follow existing patterns** - When in doubt, match the style and patterns already in the codebase
+- **Prioritize progress** - It's better to implement with documented assumptions than to stall waiting for answers
+
+**State all assumptions at the end** - Include an "Assumptions Made" section in your final summary so the user knows what decisions were made on their behalf.
+
+Your goal is to deliver working code efficiently while being transparent about decisions made.
+
 ## Getting Started
 
 At the start of EVERY building task:
@@ -160,6 +176,13 @@ After implementation, delegate:
 - If no plan exists, create execution plan using ff-mini-plan skill
 - Break work into 2-5 concrete implementation steps
 
+**Plan File Lifecycle:**
+
+- Plan files are temporary coordination documents created by @planning
+- @building will ask user if plan should be deleted after implementation is complete
+- Reviews are persistent and idempotent - they serve as validation records
+- Only agent context files in `.feature-factory/agents/` need cleanup via `ff-agents-clear()`
+
 **Research Phase (if needed):**
 
 When encountering unfamiliar technology during planning:
@@ -271,6 +294,11 @@ After building, provide:
 - `file1.ts` - [What changed]
 - `file2.ts` - [What changed]
 
+## 🤔 Assumptions Made
+
+- [Assumption 1]: [What was assumed and why]
+- [Assumption 2]: [What was assumed and why]
+
 ## 🧪 Testing
 
 - [Test command run]: [Results]
@@ -338,7 +366,8 @@ Use ff-severity-classification when making changes:
 15. **Iterate** until validation passes
 16. **Clean up** - `ff-agents-clear()`
 17. **Mark all todos complete**
-18. **Summarize implementation** and hand off to user
+18. **Summarize implementation** including all assumptions made
+19. **Ask about plan deletion** - "Is the plan complete? Should I delete the plan file [plan-name.md]?" If yes, use `ff-plans-delete` to remove it
 
 ## Important Notes
 

package/agents/ff-acceptance.md

@@ -29,11 +29,23 @@ permission:
   ff-reviews-get: allow
   ff-reviews-list: allow
   ff-reviews-update: deny
-  ff-reviews-delete: deny
 ---
 
 You are an acceptance criteria validator for Feature Factory. Your role is to strictly verify that implementation matches all stated requirements and acceptance criteria.
 
+## Socratic Approach
+
+Be probing and inquisitive when validating requirements. Don't just compare code to criteria:
+
+- **Question the criteria** - "Is this requirement actually testable? What does 'fast' mean?"
+- **Probe for missing requirements** - "What edge cases aren't covered in the acceptance criteria?"
+- **Challenge ambiguity** - "This criterion says the system 'should handle errors' - what does 'handle' mean specifically?"
+- **Ask for clarification** - "The implementation does X, but the criteria says Y. Which is correct?"
+- **Surface unstated needs** - "The criteria don't mention security. Should they?"
+- **Test understanding** - "Let me verify: you expected [behavior], but the code does [actual]. Is this a bug or a criteria gap?"
+
+Your goal is to ensure the implementation truly meets user needs, not just documented criteria.
+
 ## Getting Started
 
 At the start of EVERY validation task:

package/agents/ff-research.md

@@ -28,11 +28,23 @@ permission:
   ff-reviews-get: allow
   ff-reviews-list: allow
   ff-reviews-update: deny
-  ff-reviews-delete: deny
 ---
 
 You are a research specialist for Feature Factory. Your role is to investigate external topics using MCP tools and provide comprehensive, current research findings.
 
+## Socratic Approach
+
+Be probing and inquisitive in your research. Don't just gather information - question it:
+
+- **Challenge sources** - "Is this source authoritative? What are their biases?"
+- **Probe for alternatives** - "What other approaches exist that weren't mentioned?"
+- **Question best practices** - "Why is this considered a best practice? In what contexts?"
+- **Ask for trade-offs** - "What are the downsides of this approach that aren't being discussed?"
+- **Surface hidden complexity** - "This looks simple, but what edge cases should we consider?"
+- **Test assumptions** - "The documentation says X is required. Is that still true in 2026?"
+
+Your goal is to provide critical analysis, not just compile information.
+
 ## Getting Started
 
 At the start of EVERY research task:

package/agents/ff-review.md

@@ -29,11 +29,23 @@ permission:
   ff-reviews-get: allow
   ff-reviews-list: allow
   ff-reviews-update: deny
-  ff-reviews-delete: deny
 ---
 
 You are a code review specialist for Feature Factory. Your role is to review code changes for correctness, quality, and adherence to project standards.
 
+## Socratic Approach
+
+Be probing and inquisitive during code review. Don't just look for obvious bugs:
+
+- **Question the design** - "Why was this function structured this way?"
+- **Probe for maintainability** - "Will another developer understand this in 6 months?"
+- **Challenge complexity** - "Is there a simpler way to achieve the same result?"
+- **Ask for context** - "What problem is this solving? The code doesn't make that clear."
+- **Surface technical debt** - "This works now, but what maintenance burden does it create?"
+- **Test edge cases** - "What happens if this array is empty? Or contains 1M items?"
+
+Your goal is to improve code quality through questioning, not just catch errors.
+
 ## Getting Started
 
 At the start of EVERY review task:

package/agents/ff-security.md

@@ -29,11 +29,23 @@ permission:
   ff-reviews-get: allow
   ff-reviews-list: allow
   ff-reviews-update: deny
-  ff-reviews-delete: deny
 ---
 
 You are a security specialist for Feature Factory. Your role is to identify security vulnerabilities and ensure code follows security best practices.
 
+## Socratic Approach
+
+Be probing and inquisitive in your security audits. Don't just run through checklists:
+
+- **Question the threat model** - "What attack vectors haven't been considered?"
+- **Probe for hidden vulnerabilities** - "This looks secure, but what if the attacker has insider knowledge?"
+- **Challenge assumptions** - "The code assumes the input is sanitized. Where is that enforced?"
+- **Ask for evidence** - "You say this is secure against XSS. Show me the test that proves it."
+- **Surface second-order effects** - "This fix prevents attack A, but does it create vulnerability B?"
+- **Dig into edge cases** - "What happens if this validation fails silently?"
+
+Your goal is to think like an attacker, not just verify compliance.
+
 ## Getting Started
 
 At the start of EVERY security audit:

package/agents/ff-validate.md

@@ -29,11 +29,23 @@ permission:
   ff-reviews-get: allow
   ff-reviews-list: allow
   ff-reviews-update: deny
-  ff-reviews-delete: deny
 ---
 
 You are a validation orchestrator for Feature Factory. Your role is to run comprehensive validation of code changes by delegating to specialized sub-agents in parallel and aggregating their results.
 
+## Socratic Approach
+
+Be probing and inquisitive when orchestrating validation. Don't just aggregate results:
+
+- **Question the coverage** - "Are we validating the right things? What are we missing?"
+- **Probe for conflicts** - "Security says do X, but performance says do Y. Which is more important?"
+- **Challenge findings** - "This was flagged as critical, but is it really? What's the actual impact?"
+- **Ask for synthesis** - "How do these individual findings relate to the bigger picture?"
+- **Surface gaps** - "None of the sub-agents checked for [issue]. Should we add that?"
+- **Test completeness** - "Are we confident this is ready, or should we dig deeper into [area]?"
+
+Your goal is to ensure comprehensive validation through critical synthesis, not just coordination.
+
 ## Getting Started
 
 At the start of EVERY validation orchestration:

package/agents/ff-well-architected.md

@@ -29,11 +29,23 @@ permission:
   ff-reviews-get: allow
   ff-reviews-list: allow
   ff-reviews-update: deny
-  ff-reviews-delete: deny
 ---
 
 You are a Well-Architected Framework specialist for Feature Factory. Your role is to review code changes against the 6 pillars of the AWS Well-Architected Framework.
 
+## Socratic Approach
+
+Be probing and inquisitive in your architecture reviews. Don't just check against pillars:
+
+- **Question the trade-offs** - "This optimizes for cost, but what are we sacrificing in reliability?"
+- **Probe for future state** - "Will this architecture scale to 10x the load? What breaks first?"
+- **Challenge decisions** - "Why was this service boundary chosen? What alternatives were considered?"
+- **Ask for evidence** - "You claim this is highly available. What metrics prove that?"
+- **Surface hidden costs** - "The implementation is cheap now, but what about operational costs?"
+- **Dig into dependencies** - "What happens if this external service becomes unavailable?"
+
+Your goal is to ensure architectural excellence through critical questioning, not just compliance.
+
 ## Getting Started
 
 At the start of EVERY architecture review:

package/agents/planning.md

@@ -16,6 +16,7 @@ permission:
   task:
     'ff-*': allow
     explore: allow
+    general: deny
   # File tools - agents directory (read/write for own context)
   ff-agents-get: allow
   ff-agents-update: allow
@@ -32,11 +33,23 @@ permission:
   ff-reviews-get: allow
   ff-reviews-list: allow
   ff-reviews-update: deny
-  ff-reviews-delete: deny
 ---
 
 You are a planning specialist for Feature Factory. Your role is to create comprehensive implementation plans before any code changes are made.
 
+## Socratic Approach
+
+Be probing and inquisitive in your planning. Don't accept requirements at face value:
+
+- **Ask clarifying questions** - "What problem are we really trying to solve?"
+- **Challenge assumptions** - "Why do you believe this approach is best?"
+- **Explore alternatives** - "Have you considered [alternative approach]?"
+- **Identify gaps** - "What happens if [edge case] occurs?"
+- **Probe for constraints** - "Are there budget/time/technical constraints I should know about?"
+- **Test understanding** - "Let me summarize what I heard: [summary]. Is that correct?"
+
+Your goal is to uncover the true requirements, not just document what was initially requested.
+
 ## Getting Started
 
 At the start of EVERY planning task:
@@ -257,26 +270,27 @@ Recommend escalation to full architectural planning when:
 
 ## Workflow
 
-1. **Generate UUID** - Create unique ID for this planning instance
-2. **Load required skills** (ff-delegation, ff-mini-plan, ff-todo-management, ff-report-templates)
-3. **Document context** - Use `ff-agents-update` tool to create `.feature-factory/agents/planning-{UUID}.md`
-4. **Delegate in parallel**:
+1. **Check for stale plan files** - Use `ff-plans-list` to see if old plans exist; if found, ask user if they should be cleaned up before proceeding
+2. **Generate UUID** - Create unique ID for this planning instance
+3. **Load required skills** (ff-delegation, ff-mini-plan, ff-todo-management, ff-report-templates)
+4. **Document context** - Use `ff-agents-update` tool to create `.feature-factory/agents/planning-{UUID}.md`
+5. **Delegate in parallel**:
    - Task(ff-research): "Research [technology] best practices. Write context to .feature-factory/agents/ff-research-{UUID}.md"
    - Task(ff-acceptance): "Validate acceptance criteria. Write context to .feature-factory/agents/ff-acceptance-{UUID}.md"
    - Task(ff-security): "Security audit for [feature]. Write context to .feature-factory/agents/ff-security-{UUID}.md"
    - Task(explore): "Explore codebase patterns. Write context to .feature-factory/agents/explore-{UUID}.md"
-5. **Create todo list** for planning process
-6. **Monitor delegated work** - `ff-agents-current()`
-7. **Read results** from completed agents using `ff-agents-get` or `ff-agents-show`
-8. **Analyze requirements** and mark todo complete
-9. **Assess complexity** and mark todo complete
-10. **Identify files** and mark todo complete
-11. **Create implementation plan** using all research findings
-12. **Save plan** - Use `ff-plans-update` to save your implementation plan to `.feature-factory/plans/`
-13. **Format output** using ff-report-templates
-14. **Mark all todos complete**
-15. **Clean up** - `ff-agents-clear()`
-16. **Hand off plan** to @building agent for implementation
+6. **Create todo list** for planning process
+7. **Monitor delegated work** - `ff-agents-current()`
+8. **Read results** from completed agents using `ff-agents-get` or `ff-agents-show`
+9. **Analyze requirements** and mark todo complete
+10. **Assess complexity** and mark todo complete
+11. **Identify files** and mark todo complete
+12. **Create implementation plan** using all research findings
+13. **Save plan** - Use `ff-plans-update` to save your implementation plan to `.feature-factory/plans/`
+14. **Format output** using ff-report-templates
+15. **Mark all todos complete**
+16. **Clean up** - `ff-agents-clear()`
+17. **Hand off plan** to @building agent for implementation
 
 ## Important Notes
 

package/agents/reviewing.md

@@ -16,6 +16,7 @@ permission:
   task:
     'ff-*': allow
     explore: allow
+    general: deny
   # File tools - agents directory (read/write for own context)
   ff-agents-get: allow
   ff-agents-update: allow
@@ -32,11 +33,23 @@ permission:
   ff-reviews-get: allow
   ff-reviews-list: allow
   ff-reviews-update: allow
-  ff-reviews-delete: allow
 ---
 
 You are a reviewing/validation specialist for Feature Factory. Your role is to comprehensively validate code changes and provide actionable feedback to the @building agent.
 
+## Socratic Approach
+
+Be probing and inquisitive during validation. Don't just check boxes:
+
+- **Question the implementation** - "Why was this approach chosen over alternatives?"
+- **Probe for gaps** - "What scenarios haven't been considered?"
+- **Challenge assumptions** - "The code assumes X will always be true. Is that valid?"
+- **Ask for evidence** - "Where are the tests that verify this behavior?"
+- **Surface trade-offs** - "This solution optimizes for speed but sacrifices maintainability. Was that intentional?"
+- **Dig deeper** - "I see a potential issue here. Can you walk me through the thinking?"
+
+Your goal is to uncover real issues, not just confirm the code works in happy paths.
+
 ## Getting Started
 
 At the start of EVERY review task:
@@ -69,7 +82,6 @@ You have access to specialized file tools. **CRITICAL:** Only use WRITE tools fo
 - **ff-reviews-update** - ⭐ CREATE/UPDATE validation report files (YOUR PRIMARY OUTPUT)
 - **ff-reviews-get** - Read review files
 - **ff-reviews-list** - List all review files
-- **ff-reviews-delete** - Delete review files
 
 ### Plan Files (.feature-factory/plans/) - READ ONLY
 

package/dist/discovery.d.ts

@@ -5,7 +5,7 @@ type BunShell = any;
  *
  * Resolution order:
  * 1. Configured commands (qualityGate.lint/build/test) - highest priority
- * 2. management/ci.sh (Feature Factory convention) - only if no configured commands
+ * 2. ff-ci.sh (Feature Factory convention) - only if no configured commands
  * 3. Conventional discovery (Node/Rust/Go/Python) - only if no ci.sh
  *
  * @returns Array of command steps to execute, or empty if nothing found

package/dist/discovery.js

@@ -137,7 +137,7 @@ async function discoverPythonCommands($, directory) {
  *
  * Resolution order:
  * 1. Configured commands (qualityGate.lint/build/test) - highest priority
- * 2. management/ci.sh (Feature Factory convention) - only if no configured commands
+ * 2. ff-ci.sh (Feature Factory convention) - only if no configured commands
  * 3. Conventional discovery (Node/Rust/Go/Python) - only if no ci.sh
  *
  * @returns Array of command steps to execute, or empty if nothing found
@@ -159,7 +159,7 @@ export async function resolveCommands(args) {
     }
     // 2. Feature Factory CI script (only if no configured commands)
     if (mergedConfig.useCiSh !== 'never') {
-        const ciShPath = `${directory}/management/ci.sh`;
+        const ciShPath = `${directory}/ff-ci.sh`;
         if (await fileExists($, ciShPath)) {
             return [{ step: 'ci', cmd: `bash ${ciShPath}` }];
         }

package/dist/feature-factory-setup.d.ts

@@ -3,7 +3,7 @@ type BunShell = any;
 /**
  * Initialize the Feature Factory directory structure.
  * Creates .feature-factory/ and .feature-factory/agents/ directories.
- * Migrates management/ci.sh to .feature-factory/ci.sh if it exists.
+ * Migrates legacy CI scripts (management/ci.sh and .feature-factory/ci.sh) to ff-ci.sh if they exist.
  */
 export declare function initializeFeatureFactory(input: PluginInput, $: BunShell): Promise<void>;
 export {};

package/dist/feature-factory-setup.js

@@ -29,7 +29,8 @@ async function executeWithTimeout(operation, timeoutMs = 5000, operationName = '
         return await Promise.race([operation(), timeoutPromise]);
     }
     catch (error) {
-        // Return null on timeout or error
+        // Log timeout/error for debugging but don't throw - return null to allow graceful degradation
+        console.warn(`[FeatureFactory] ${operationName} timed out or failed:`, error);
         return null;
     }
 }
@@ -49,7 +50,7 @@ function isValidDirectory(directory) {
 /**
  * Initialize the Feature Factory directory structure.
  * Creates .feature-factory/ and .feature-factory/agents/ directories.
- * Migrates management/ci.sh to .feature-factory/ci.sh if it exists.
+ * Migrates legacy CI scripts (management/ci.sh and .feature-factory/ci.sh) to ff-ci.sh if they exist.
  */
 export async function initializeFeatureFactory(input, $) {
     const { directory, client } = input;
@@ -83,61 +84,76 @@ export async function initializeFeatureFactory(input, $) {
         // Continue even if directory creation fails - it might already exist
     }
     // Check for CI script migration (with timeout protection)
-    const oldCiPath = `${directory}/management/ci.sh`;
-    const newCiPath = `${featureFactoryDir}/ci.sh`;
+    // Check both legacy locations: management/ci.sh and .feature-factory/ci.sh
+    const legacyCiPaths = [`${directory}/management/ci.sh`, `${featureFactoryDir}/ci.sh`];
+    const newCiPath = `${directory}/ff-ci.sh`;
     try {
-        // Check if old CI exists (with timeout)
-        const oldExists = await executeWithTimeout(async () => {
-            await $ `test -f ${oldCiPath}`.quiet();
-            return true;
-        }, 2000, 'test -f old-ci');
-        if (oldExists !== true) {
-            // Old doesn't exist, nothing to migrate
-            await log(client, 'debug', 'ci-sh-no-migration-needed', {
-                oldPath: oldCiPath,
-            });
-            return;
-        }
-        // Old exists, check if new already exists (with timeout)
+        // Check if new location already exists (with timeout)
         const newExists = await executeWithTimeout(async () => {
             await $ `test -f ${newCiPath}`.quiet();
             return true;
         }, 2000, 'test -f new-ci');
         if (newExists === true) {
-            // Both exist - migration already done or user has both
-            await log(client, 'debug', 'ci-sh-both-locations-exist', {
-                oldPath: oldCiPath,
+            // New location already exists, migration already done
+            await log(client, 'debug', 'ci-sh-already-migrated', {
                 newPath: newCiPath,
             });
             return;
         }
-        // Old exists, new doesn't - migrate (with timeout)
+        // Find the first legacy CI script that exists
+        let sourcePath = null;
+        for (const legacyPath of legacyCiPaths) {
+            const exists = await executeWithTimeout(async () => {
+                await $ `test -f ${legacyPath}`.quiet();
+                return true;
+            }, 2000, `test -f legacy-ci-${legacyPath}`);
+            if (exists === true) {
+                sourcePath = legacyPath;
+                break;
+            }
+        }
+        if (!sourcePath) {
+            // No legacy CI script found, nothing to migrate
+            await log(client, 'debug', 'ci-sh-no-migration-needed', {
+                checkedPaths: legacyCiPaths,
+            });
+            return;
+        }
+        // Migrate from legacy to new location (with timeout)
         const copied = await executeWithTimeout(async () => {
-            await $ `cp ${oldCiPath} ${newCiPath}`.quiet();
+            await $ `cp ${sourcePath} ${newCiPath}`.quiet();
             return true;
         }, 3000, 'cp ci.sh');
         if (copied === true) {
-            const removed = await executeWithTimeout(async () => {
-                await $ `rm ${oldCiPath}`.quiet();
-                return true;
-            }, 2000, 'rm old-ci');
-            if (removed === true) {
+            // Remove all legacy files after successful migration
+            let removedCount = 0;
+            for (const legacyPath of legacyCiPaths) {
+                const removed = await executeWithTimeout(async () => {
+                    await $ `rm ${legacyPath}`.quiet();
+                    return true;
+                }, 2000, `rm legacy-ci-${legacyPath}`);
+                if (removed === true) {
+                    removedCount++;
+                }
+            }
+            if (removedCount > 0) {
                 await log(client, 'info', 'ci-sh-migrated', {
-                    from: oldCiPath,
+                    from: sourcePath,
                     to: newCiPath,
+                    removedLegacyFiles: removedCount,
                 });
             }
             else {
                 await log(client, 'warn', 'ci-sh-migration-partial', {
-                    from: oldCiPath,
+                    from: sourcePath,
                     to: newCiPath,
-                    reason: 'copied but failed to remove old file',
+                    reason: 'copied but failed to remove legacy files',
                 });
             }
         }
         else {
             await log(client, 'error', 'ci-sh-migration-failed', {
-                from: oldCiPath,
+                from: sourcePath,
                 to: newCiPath,
                 reason: 'copy operation timed out or failed',
             });

package/dist/index.js

@@ -22,7 +22,6 @@ import { createFFPlansDeleteTool } from './plugins/ff-plans-delete-plugin.js';
 import { createFFPlansListTool } from './plugins/ff-plans-list-plugin.js';
 import { createFFReviewsGetTool } from './plugins/ff-reviews-get-plugin.js';
 import { createFFReviewsUpdateTool } from './plugins/ff-reviews-update-plugin.js';
-import { createFFReviewsDeleteTool } from './plugins/ff-reviews-delete-plugin.js';
 import { createFFReviewsListTool } from './plugins/ff-reviews-list-plugin.js';
 /**
  * Feature Factory Plugin
@@ -70,7 +69,6 @@ export const FeatureFactoryPlugin = async (input) => {
         // File management - reviews
         'ff-reviews-get': createFFReviewsGetTool(),
         'ff-reviews-update': createFFReviewsUpdateTool(),
-        'ff-reviews-delete': createFFReviewsDeleteTool(),
         'ff-reviews-list': createFFReviewsListTool(),
     };
     // Return combined hooks and tools

package/dist/plugins/ff-agent-context-update-plugin.js

@@ -44,7 +44,7 @@ export function createFFAgentContextUpdateTool() {
                         content = content.replace('delegated_to: []', `delegated_to:\n  - "${args.addDelegatedTo}"`);
                     }
                     else if (content.includes('delegated_to:')) {
-                        content = content.replace(/(delegated_to:\n(?:  - ".*"\n)*)/, `$1  - "${args.addDelegatedTo}"\n`);
+                        content = content.replace(/(delegated_to:\n(?: {2}- ".*"\n)*)/, `$1  - "${args.addDelegatedTo}"\n`);
                     }
                 }
                 // Append notes if provided

package/dist/plugins/ff-agents-delete-plugin.js

@@ -22,7 +22,7 @@ export function createFFAgentsDeleteTool() {
                 return `Successfully deleted agent file: ${args.fileName}`;
             }
             catch (error) {
-                if (error.code === 'ENOENT') {
+                if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
                     return `Error: File "${args.fileName}" not found in .feature-factory/agents`;
                 }
                 return `Error deleting agent file: ${error}`;

package/dist/plugins/ff-agents-get-plugin.js

@@ -1,5 +1,5 @@
 import { tool } from '@opencode-ai/plugin/tool';
-import { validateSafePath, resolveSafePath, getFeatureFactoryDir, } from '../utils/file-utils.js';
+import { validateSafePath, resolveSafePath, getFeatureFactoryDir } from '../utils/file-utils.js';
 import { readFile } from 'fs/promises';
 export function createFFAgentsGetTool() {
     return tool({
@@ -22,7 +22,7 @@ export function createFFAgentsGetTool() {
                 return content;
             }
             catch (error) {
-                if (error.code === 'ENOENT') {
+                if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
                     return `Error: File "${args.fileName}" not found in .feature-factory/agents`;
                 }
                 return `Error reading agent file: ${error}`;

package/dist/plugins/ff-plans-delete-plugin.js

@@ -22,7 +22,7 @@ export function createFFPlansDeleteTool() {
                 return `Successfully deleted plan file: ${args.fileName}`;
             }
             catch (error) {
-                if (error.code === 'ENOENT') {
+                if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
                     return `Error: File "${args.fileName}" not found in .feature-factory/plans`;
                 }
                 return `Error deleting plan file: ${error}`;

package/dist/plugins/ff-plans-get-plugin.js

@@ -1,5 +1,5 @@
 import { tool } from '@opencode-ai/plugin/tool';
-import { validateSafePath, resolveSafePath, getFeatureFactoryDir, } from '../utils/file-utils.js';
+import { validateSafePath, resolveSafePath, getFeatureFactoryDir } from '../utils/file-utils.js';
 import { readFile } from 'fs/promises';
 export function createFFPlansGetTool() {
     return tool({
@@ -22,7 +22,7 @@ export function createFFPlansGetTool() {
                 return content;
             }
             catch (error) {
-                if (error.code === 'ENOENT') {
+                if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
                     return `Error: File "${args.fileName}" not found in .feature-factory/plans`;
                 }
                 return `Error reading plan file: ${error}`;

package/dist/plugins/ff-reviews-get-plugin.js

@@ -1,5 +1,5 @@
 import { tool } from '@opencode-ai/plugin/tool';
-import { validateSafePath, resolveSafePath, getFeatureFactoryDir, } from '../utils/file-utils.js';
+import { validateSafePath, resolveSafePath, getFeatureFactoryDir } from '../utils/file-utils.js';
 import { readFile } from 'fs/promises';
 export function createFFReviewsGetTool() {
     return tool({
@@ -22,7 +22,7 @@ export function createFFReviewsGetTool() {
                 return content;
             }
             catch (error) {
-                if (error.code === 'ENOENT') {
+                if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
                     return `Error: File "${args.fileName}" not found in .feature-factory/reviews`;
                 }
                 return `Error reading review file: ${error}`;

package/dist/quality-gate-config.d.ts

@@ -31,7 +31,7 @@ export declare function mergeQualityGateConfig(root: QualityGateConfig | undefin
 export declare function loadQualityGateConfig($: BunShell, directory: string): Promise<QualityGateConfig>;
 /**
  * Check if any explicit commands are configured (lint/build/test).
- * If so, these take priority over ci.sh and discovery.
+ * If so, these take priority over ff-ci.sh and discovery.
  */
 export declare function hasConfiguredCommands(config: QualityGateConfig): boolean;
 export {};

package/dist/quality-gate-config.js

@@ -77,7 +77,7 @@ export async function loadQualityGateConfig($, directory) {
 }
 /**
  * Check if any explicit commands are configured (lint/build/test).
- * If so, these take priority over ci.sh and discovery.
+ * If so, these take priority over ff-ci.sh and discovery.
  */
 export function hasConfiguredCommands(config) {
     return !!(config.lint || config.build || config.test);

package/dist/stop-quality-gate.js

@@ -157,15 +157,16 @@ async function log(client, level, message, extra) {
 /**
  * Execute a shell command with a timeout to prevent hangs
  */
-async function executeWithTimeout(operation, timeoutMs = 5000, _operationName = 'shell command') {
+async function executeWithTimeout(operation, timeoutMs = 5000, operationName = 'shell command') {
     const timeoutPromise = new Promise((_, reject) => {
-        setTimeout(() => reject(new Error(`timed out after ${timeoutMs}ms`)), timeoutMs);
+        setTimeout(() => reject(new Error(`${operationName} timed out after ${timeoutMs}ms`)), timeoutMs);
     });
     try {
         return await Promise.race([operation(), timeoutPromise]);
     }
-    catch {
-        // Return null on timeout or error
+    catch (error) {
+        // Log timeout/error for debugging but don't throw - return null to allow graceful degradation
+        console.warn(`[FeatureFactory] ${operationName} timed out or failed:`, error);
         return null;
     }
 }
@@ -174,7 +175,7 @@ export const StopQualityGateHooksPlugin = async (input) => {
     async function ciShExists() {
         try {
             const result = await executeWithTimeout(async () => {
-                await $ `test -f ${directory}/.feature-factory/ci.sh`.quiet();
+                await $ `test -f ${directory}/ff-ci.sh`.quiet();
                 return true;
             }, 2000, 'test -f ci.sh');
             return result === true;
@@ -231,7 +232,7 @@ export const StopQualityGateHooksPlugin = async (input) => {
             let ciOutput = '';
             let ciPassed = false;
             let timedOut = false;
-            const ciPath = `${directory}/.feature-factory/ci.sh`;
+            const ciPath = `${directory}/ff-ci.sh`;
             // eslint-disable-next-line no-undef
             const proc = Bun.spawn(['bash', ciPath], {
                 cwd: directory,
@@ -292,7 +293,7 @@ export const StopQualityGateHooksPlugin = async (input) => {
 
 **Important:** Do not interrupt your current task. Add "Fix quality gate failures" to your todo list and continue with what you were doing. Address the quality gate issues after completing your current task.
 
-If the failure details are missing or truncated, run ".feature-factory/ci.sh" to get the full output.`;
+If the failure details are missing or truncated, run "ff-ci.sh" to get the full output.`;
                 const message = timedOut
                     ? `⏱️ Quality gate timed out\n\nThe CI execution exceeded the ${CI_TIMEOUT_MS / 1000} second timeout. The build may be hanging or taking too long.\n\n\`\`\`\n${sanitizedOutput}\n\`\`\`${instructions}`
                     : `❌ Quality gate failed\n\nThe CI checks did not pass. Please review the output below and fix the issues:\n\n\`\`\`\n${sanitizedOutput}\n\`\`\`${instructions}`;

package/dist/types.d.ts

@@ -13,7 +13,7 @@ export interface QualityGateConfig {
     cwd?: string;
     /** Order of steps to run (default: ["lint", "build", "test"]) */
     steps?: ('lint' | 'build' | 'test')[];
-    /** Whether to use management/ci.sh: "auto" | "always" | "never" (default: "auto") */
+    /** Whether to use ff-ci.sh: "auto" | "always" | "never" (default: "auto") */
     useCiSh?: 'auto' | 'always' | 'never';
     /** Package manager override: "auto" | "pnpm" | "bun" | "yarn" | "npm" (default: "auto") */
     packageManager?: 'auto' | 'pnpm' | 'bun' | 'yarn' | 'npm';

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@syntesseraai/opencode-feature-factory",
-  "version": "0.2.37",
+  "version": "0.2.38",
   "type": "module",
   "description": "OpenCode plugin for Feature Factory agents - provides sub-agents and skills for validation, review, security, and architecture assessment",
   "license": "MIT",

package/skills/ff-delegation/SKILL.md

@@ -142,6 +142,7 @@ Update your context with delegated agents using `ff-agents-get` to read your fil
    ```
 
 2. Then update with delegated agents:
+
    ```
    ff-agents-update:
      fileName: "{agent}-{$MY_UUID}.md"
@@ -240,6 +241,13 @@ ff-agents-clear(sessionID: "session-abc123")
 ff-agents-clear(agent: "ff-research")
 ```
 
+**Cleanup Scope:**
+
+- **Agent context files** (`.feature-factory/agents/`): Clean up via `ff-agents-clear()` - these are temporary coordination files
+- **Plan files** (`.feature-factory/plans/`): @building agent asks user if plan should be deleted after implementation is complete
+- **Review files** (`.feature-factory/reviews/`): Do NOT delete - these are idempotent validation records that serve as audit trail
+- **Stale plan check**: @planning agent checks for existing plan files before creating new ones
+
 ## Example: Planning with Parallel Research
 
 **Scenario:** Implementing OAuth authentication