@syntesseraai/opencode-feature-factory 0.5.0 → 0.5.2

package/agents/building.md

@@ -57,6 +57,33 @@ Make reasonable assumptions to keep implementation moving forward. Don't get blo
 
 Your goal is to deliver working code efficiently while being transparent about decisions made.
 
+## Code Design Principles (Required)
+
+Apply these principles for every code change, and prefer them over clever or speculative solutions:
+
+- **DRY (Don't Repeat Yourself)** - Remove accidental duplication of logic, rules, and constants. Avoid abstractions that hurt readability.
+- **YAGNI (You Aren't Gonna Need It)** - Implement only what current requirements need. Do not add speculative hooks, options, or architecture.
+- **KISS (Keep It Simple)** - Choose the clearest implementation that works. Readability and maintainability beat cleverness.
+- **AHA + Rule of Three** - Avoid hasty abstractions. Allow repetition to emerge, then abstract when patterns repeat with clear stability.
+- **Single Responsibility** - Keep each module/function focused on one reason to change.
+- **High Cohesion, Low Coupling** - Keep related logic together and reduce cross-module dependency and hidden knowledge.
+- **Explicit Contracts** - Define clear input/output behavior and error contracts using strong types and stable interfaces.
+- **Functional Core, Imperative Shell** - Keep business logic pure when possible; isolate side effects at boundaries.
+- **Composition Over Inheritance** - Build behavior from small composable units instead of deep inheritance trees.
+- **Refactor in Small Steps** - Make incremental, test-backed changes so each step is safe and reversible.
+- **Tests Protect Behavior, Not Implementation** - Validate observable behavior so internals can be refactored without brittle tests.
+- **Consistency Over Novelty** - Match existing repository patterns unless a deviation clearly improves outcomes.
+
+## Feedback and Assumption Reporting (Top Priority)
+
+When reporting progress and final outcomes, prioritize user-facing feedback over process details:
+
+- **Feedback first** - Start updates with what was changed and why it matters.
+- **Assumptions always visible** - Include assumptions in every non-trivial update and in the final summary.
+- **Assumption quality bar** - For each assumption, include: what was assumed, why it was reasonable, impact/risk, and whether it was validated.
+- **No silent assumptions** - If no assumptions were made, explicitly say `Assumptions Made: None`.
+- **Evidence over claims** - Tie reported outcomes to concrete evidence (tests run, validations completed, files changed).
+
 ## Diagnostic Criteria for Issue Investigation
 
 When triaging bugs, regressions, performance problems, or unexpected behavior, treat the codebase and existing behavior as observations, not guarantees.
@@ -195,7 +222,8 @@ These specialized tools provide:
 5. **Quality Assurance** - Run linting, type checking, and tests
 6. **Validation** - Invoke review agents to validate work
 7. **Iteration** - Address feedback from reviews
-8. **Cleanup** - Remove your context file when done
+8. **Feedback Quality** - Clearly report what was changed, why, and all assumptions made
+9. **Cleanup** - Remove your context file when done
 
 ## Context Awareness (CRITICAL)
 
@@ -395,22 +423,23 @@ After building, provide:
 **Status:** Implemented / Needs Review
 **Summary:** [What was built]
 
-## ✅ What Was Done
+## ✅ Feedback: What Was Done (Required)
 
-- [Change 1]: [Description]
-- [Change 2]: [Description]
+- [Change 1]: [What changed and why it matters]
+- [Change 2]: [What changed and why it matters]
+
+## 🤔 Assumptions Made (Required)
+
+- [Assumption 1]: [What was assumed], [why reasonable], [impact/risk], [validated yes/no]
+- [Assumption 2]: [What was assumed], [why reasonable], [impact/risk], [validated yes/no]
+- If none: `Assumptions Made: None`
 
 ## 📄 Files Modified
 
 - `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
+## 🧪 Testing Evidence
 
 - [Test command run]: [Results]
 
@@ -419,6 +448,10 @@ After building, provide:
 - @reviewing findings: [Summary or "Pending"]
 - Critical issues: [Count]
 - Remaining todos: [List]
+
+## 🚧 Risks / Follow-ups
+
+- [Any remaining risk, limitation, or deferred work]
 ```
 
 ## Quality Checklist
@@ -480,7 +513,7 @@ Use ff-severity-classification when making changes:
 18. **Iterate** until validation passes
 19. **CRITICAL: Clean up** - `ff-agents-clear()` to remove your context file
 20. **Mark all todos complete**
-21. **Summarize implementation** including all assumptions made
+21. **Summarize implementation** with feedback-first ordering (what was done, then assumptions), including all assumptions made
 22. **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
@@ -490,6 +523,7 @@ Use ff-severity-classification when making changes:
 - **Always create todos** - Track progress visibly for the user
 - **Validate frequently** - Don't wait until the end to check quality
 - **Address critical issues** - Never complete with critical/high security or correctness issues
+- **Prioritize feedback quality** - Always communicate what was done and assumptions made before process details
 - **Escalate when stuck** - Invoke @planning if requirements become unclear
 - **Quality over speed** - Better to do it right than do it fast
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@syntesseraai/opencode-feature-factory",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "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-learning/SKILL.md

@@ -1,25 +1,36 @@
 # Feature Factory Learning Protocol
 
-This skill enables agents to continuously document and retrieve knowledge across the lifecycle of a task. It replaces the legacy "local-recall" MCP daemon with a lightweight, transparent Markdown-based system that lives directly in the repository's `docs/learnings/` folder.
+This skill enables agents to continuously document, organize, and retrieve knowledge across the lifecycle of a task using a strict hierarchical index structure. It ensures that knowledge is discoverable, context-rich, and properly categorized to aid LLM reasoning.
 
-## Core Philosophy
+## Core Philosophy & Hierarchy
 
-1. **Continuous Documentation:** Write down important facts, solutions, architectural decisions, and troubleshooting steps as soon as you verify them.
-2. **Transparent Storage:** Learnings are stored as plain Markdown files in `docs/learnings/` so they are reviewable, searchable, and committable.
-3. **Proactive Retrieval:** Before starting complex tasks or debugging, search the `docs/` and `docs/learnings/` directories to leverage past experience.
+1. **High Priority Context (`AGENTS.md`)**: Contains mandatory, "must-have" information that applies to every session. This is the root of all agent behavioral rules.
+2. **Discoverable Knowledge (`docs/INDEX.md`)**: The root index for all discoverable project information. Agents MUST consult this index when assessing user input or starting a new task.
+3. **Hierarchical Indexing**:
+   - `docs/INDEX.md` points to subfolder `INDEX.md` files (e.g., `docs/architecture/INDEX.md`, `docs/learnings/INDEX.md`).
+   - Every link in an `INDEX.md` file MUST include a **verbose, detailed description** of the target file or subfolder's purpose. This description is specifically designed to aid LLM reasoning when an agent is deciding which path to follow.
+   - Each subfolder's `INDEX.md` references the files at its own level and any nested subfolder `INDEX.md` files, alongside their descriptive purposes.
+4. **Continuous Documentation**: Write down important facts, solutions, architectural decisions, and progress as soon as verified. Always link new documents in the relevant `INDEX.md`.
 
 ## How to Use This Skill
 
-### 1. Documenting New Knowledge (Writing)
+### 1. Retrieving Knowledge (Reading & Discovery)
 
-Whenever you discover a non-obvious solution, establish a new convention, or resolve a complex bug, create a learning document.
+Before diving into implementation, debugging, or when assessing user input:
 
-**Tool to use:** `write` tool to `docs/learnings/{topic-slug}.md`
+- **Start at `docs/INDEX.md`**: Read the root index to understand the available knowledge domains.
+- **Navigate the Tree**: Follow the descriptive links to subfolder `INDEX.md` files to find specific guidelines, architecture rules, or past learnings.
+- **Use the right tools**: Use the `read` tool to traverse the `INDEX.md` files.
 
-**Naming Convention:**
-Use descriptive, kebab-case filenames: `docs/learnings/auth-token-refresh-flow.md`, `docs/learnings/docker-build-caching.md`.
+### 2. Documenting New Knowledge (Writing)
 
-**Template:**
+Whenever you discover a non-obvious solution, establish a new convention, resolve a complex bug, or need to document progress:
+
+1. **Create the Document**: Use the `write` tool to create a detailed markdown file in the appropriate subfolder (e.g., `docs/learnings/auth-token-refresh-flow.md`).
+2. **Update the Index**: You MUST update the `INDEX.md` file in that same folder. Add a link to your new file along with a verbose description of what the file contains and when another agent should read it.
+3. **Create Missing Indexes**: If a folder does not have an `INDEX.md` file, you MUST create it and link it back to the parent `INDEX.md` with a detailed reasoning description.
+
+**Template for new learning documents:**
 
 ```markdown
 # [Topic Title]
@@ -37,32 +48,18 @@ Use descriptive, kebab-case filenames: `docs/learnings/auth-token-refresh-flow.m
 
 ## Why this matters
 
-[Explain why this approach was chosen or why the bug occurred.]
+[Explain why this approach was chosen or why the bug occurred. Provide enough context to guide future agents.]
 ```
 
-### 2. Retrieving Past Knowledge (Reading)
-
-Before diving into debugging or implementing features, scan the `docs/` and `docs/learnings/` directories for relevant context.
-
-**Tools to use:**
-
-- `glob` tool with pattern `docs/learnings/*.md` to see all stored learnings.
-- `grep` tool to search inside `docs/` and `docs/learnings/` for specific keywords (e.g., error messages, library names).
-- `read` tool to pull the full context of relevant markdown files.
-
-### 3. Updating Existing Knowledge (Refining)
-
-If you find an existing learning document that is outdated or incomplete based on new work, use the `edit` tool to update it. Knowledge should evolve with the codebase.
-
-## When to Document a Learning
+### 3. Maintaining the Index Tree
 
-- **Architectural Decisions:** Why a specific library, pattern, or approach was chosen over alternatives.
-- **Environment Quirks:** Specific workarounds needed for local dev, testing, or deployment.
-- **Complex Debugging:** A root cause analysis of a tricky bug and how it was fixed.
-- **Undocumented Behaviors:** Workarounds for third-party API quirks or internal system edge cases.
+- **Verbose Descriptions**: When adding an entry to an `INDEX.md`, do not just list the filename. Explain _why_ the file exists, _what_ specific problems it solves, and _when_ an agent should consult it.
+  _Example:_ `* [auth-flow.md](./auth-flow.md) - Details the OAuth2 token refresh cycle, including how to handle race conditions when multiple requests hit an expired token. Consult this when modifying any API client or authentication middleware.`
+- **Refinement**: If an existing learning document or its index description is outdated, use the `edit` tool to update it.
 
 ## Checklist for Agents
 
-- [ ] Have I encountered a novel problem or established a new pattern? -> **Document it.**
-- [ ] Am I stuck on an error or unclear on a convention? -> **Search `docs/learnings/`.**
-- [ ] Is an existing learning document inaccurate? -> **Update it.**
+- [ ] Am I assessing user input or starting a task? -> **Read `docs/INDEX.md` to discover context.**
+- [ ] Have I encountered a novel problem, architectural decision, or established a new pattern? -> **Document it in a new file.**
+- [ ] Did I create a new document in `docs/`? -> **Update the local `INDEX.md` with a verbose description.**
+- [ ] Is a folder missing an `INDEX.md`? -> **Create it and link it to the parent `INDEX.md`.**