@syntesseraai/opencode-feature-factory 0.10.5 → 0.10.6

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/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@syntesseraai/opencode-feature-factory",
-  "version": "0.10.5",
+  "version": "0.10.6",
   "type": "module",
   "description": "OpenCode plugin for Feature Factory agents - provides sub-agents and skills for validation, review, security, and architecture assessment",
   "license": "MIT",
@@ -15,7 +15,8 @@
     "assets",
     "skills",
     "agents",
-    "bin"
+    "bin",
+    "AGENTS.md"
   ],
   "keywords": [
     "opencode",