@syntesseraai/opencode-feature-factory 0.5.0 → 0.5.1

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.1",
   "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`.**