ai-fob 1.2.0 → 1.2.1

package/assets/commands/build-phase-V2.md

@@ -113,7 +113,7 @@ Used during resume detection to verify step outputs are genuine and complete (no
 You (the main agent) handle this step directly.
 
 1. **Validate inputs**: Parse ARGUMENTS_RAW into HL_PLAN_PATH (first arg) and PHASE_NUMBER (second arg). If either is missing, error with: `Usage: /build-phase-V2 [path to HL plan] [phase number]`. Verify HL_PLAN_PATH exists and is a `.md` file. Read its YAML frontmatter and verify PHASE_NUMBER is an integer within the range of the `phases:` count. If out of range, error with: `Phase {N} is out of range. This plan has {count} phases (1-{count}).`
-2. **Derive variables**: Extract SPEC_DIR (parent directory of HL_PLAN_PATH), SPEC_DIR_BASENAME (basename of SPEC_DIR), TASK_NAME (from frontmatter `task:` field), PHASE_NAME (from `### Phase {N}: {Name}` header in the plan body), PHASE_NAME_KEBAB (kebab-case of PHASE_NAME), PHASE_DIR (`{SPEC_DIR}/phase{N}_{PHASE_NAME_KEBAB}/`).
+2. **Derive variables**: Extract SPEC_DIR (parent directory of HL_PLAN_PATH), SPEC_DIR_BASENAME (basename of SPEC_DIR), TASK_NAME (from frontmatter `task:` field), PHASE_NAME (from `### Phase {N}: {Name}` header in the plan body), PHASE_NAME_KEBAB (kebab-case of PHASE_NAME), PHASE_DIR (`{SPEC_DIR}/phase{N}_{PHASE_NAME_KEBAB}/`), REFERENCE_DOCUMENTS (from frontmatter `reference-documents:` field -- a list of file paths, or empty list if the field is absent).
 
 3. **Resume detection**: Determine if this phase was previously started and can be resumed.
 
@@ -230,6 +230,7 @@ You (the main agent) handle this step directly.
    Success Criteria: {count} defined
    Prior Phase Reports: {count read} | N/A (Phase 1)
    Skills Detected: {list or "None"}
+   Reference Documents: {count from REFERENCE_DOCUMENTS, or "None"}
    Resume Status: {Fresh run | Resuming from Step {RESUME_FROM} - {step name}}
    Pre-phase SHA: {PRE_PHASE_SHA | N/A (git unavailable)}
    ```
@@ -273,6 +274,12 @@ Run MARK_STEP_START(1).
    ## Detailed Specifications
    {Section 8 from HL plan, if present. If not present, omit this entire section.}
 
+   ## Reference Documents
+   {If REFERENCE_DOCUMENTS is non-empty, list each path. If empty, omit this entire section.}
+   The following documents were provided by the user as detailed reference material for this task. Read each document IN FULL using the Read tool before proceeding with your task. These contain detailed specifications, schemas, and implementation context that the plan must follow.
+   {For each path in REFERENCE_DOCUMENTS:}
+   - {path}
+
    ## Prior Phase Context
    {PRIOR_PHASE_CONTEXT if N > 1, otherwise "N/A -- this is Phase 1"}
    {If N > 1: "IMPORTANT: Explore the actual codebase state, not the HL plan's assumptions. Prior phases may have deviated from the plan."}
@@ -369,6 +376,12 @@ After research is complete, spawn the architect agent to create the implementati
    {Section 8 from HL plan, if present. If not present, omit this entire section.}
    {If present: "IMPORTANT: These are user-provided specifications. The implementation plan MUST conform to these specifications exactly. Do not simplify, generalize, or omit any detail from these specifications."}
 
+   ## Reference Documents
+   {If REFERENCE_DOCUMENTS is non-empty, list each path. If empty, omit this entire section.}
+   The following documents were provided by the user as detailed reference material for this task. Read each document IN FULL using the Read tool before proceeding with your task. These contain detailed specifications, schemas, and implementation context that the implementation plan MUST conform to.
+   {For each path in REFERENCE_DOCUMENTS:}
+   - {path}
+
    ## Prior Phase Context
    {PRIOR_PHASE_CONTEXT if N > 1, otherwise "N/A -- this is Phase 1"}
    {If N > 1: "IMPORTANT: Base your plan on the ACTUAL state described in prior phase reports, not the HL plan's original assumptions. Prior phases may have deviated from the plan."}
@@ -569,6 +582,11 @@ Read the plan at: {PHASE_DIR}/plan_V1.md
 ### Detailed Specifications
 {Section 8 from HL plan, if present. If not present: "None provided."}
 
+### Reference Documents
+{If REFERENCE_DOCUMENTS is non-empty, list each path. If empty: "None provided."}
+{For each path in REFERENCE_DOCUMENTS:}
+- {path}
+
 ### Prior Phase Context
 {PRIOR_PHASE_CONTEXT if N > 1, otherwise "N/A -- this is Phase 1"}
 
@@ -646,6 +664,12 @@ Success Criteria:
 {Section 8 from HL plan, if present. If not present, omit this entire section.}
 {If present: "IMPORTANT: These are user-provided specifications. The implementation plan MUST conform to these specifications exactly. Do not simplify, generalize, or omit any detail from these specifications."}
 
+## Reference Documents
+{If REFERENCE_DOCUMENTS is non-empty, list each path. If empty, omit this entire section.}
+The following documents were provided by the user as detailed reference material for this task. Read each document IN FULL using the Read tool before proceeding with your task. These contain detailed specifications, schemas, and implementation context that the implementation plan MUST conform to.
+{For each path in REFERENCE_DOCUMENTS:}
+- {path}
+
 ## Prior Phase Context
 {PRIOR_PHASE_CONTEXT if N > 1, otherwise "N/A -- this is Phase 1"}
 {If N > 1: "IMPORTANT: Base your plan on the ACTUAL state described in prior phase reports, not the HL plan's original assumptions. Prior phases may have deviated from the plan."}

package/assets/commands/create-highlevel-plan-phases.md

@@ -31,9 +31,14 @@ If the file exists AND its frontmatter contains `type: feature-document`:
   - Set FEATURE_DOC_CONTENT = the full content of the file
   - Extract from frontmatter: FEATURE_NAME (from `feature` field), SOURCE_REPO (from `source-repo` field), ANALYSIS_DEPTH (from `analysis-depth` field), DOC_DATE (from `date` field)
   - Set TASK_DESCRIPTION = "Reimplement: {FEATURE_NAME}" (derived from the document)
+  - Set REFERENCE_DOCUMENTS = [FEATURE_DOC_PATH]
 
 If the file does NOT exist, OR the file exists but its frontmatter does NOT contain `type: feature-document`:
   - Set IS_RE_ENGINEERING = false
+  - If the file DOES exist (but is not a feature document):
+    - Set REFERENCE_DOCUMENTS = [TASK_DESCRIPTION] (store the file path)
+  - If the file does NOT exist:
+    - Set REFERENCE_DOCUMENTS = [] (empty list)
   - Leave TASK_DESCRIPTION as-is (the user's original input)
   - Proceed with the existing workflow unchanged
 
@@ -104,6 +109,7 @@ The user provided a feature document from a reverse-engineering analysis. Use it
    - Should the scope be narrower or broader than the original feature?
    - Are there integration points in this codebase that affect the approach?
    - Are there detailed specifications (database schemas, API requirements, business rules, data structures) that the plan must incorporate? Capture any provided specifications verbatim.
+   - **Reference document collection**: Throughout this conversation, if the user mentions or provides paths to additional documents (brainstorm docs, design docs, specification docs, or any other reference files), attempt to read each path using the Read tool. If the file exists, append its path to REFERENCE_DOCUMENTS. Confirm to the user: "Added {path} to reference documents." At the end of Phase 1, present the full REFERENCE_DOCUMENTS list to the user for confirmation.
 
 8. Summarize the complete understanding (task description, category, user stories, anti-stories, phase breakdown with success criteria, and detailed specifications if any) and get explicit user confirmation.
 
@@ -120,6 +126,7 @@ The user provided a feature document from a reverse-engineering analysis. Use it
    - What success looks like
    - Any constraints (timeline, tech stack, performance)
    - **Detailed specifications**: If the user provides detailed technical requirements (database schemas, API specifications, business rules, data structures, validation rules, or other concrete specifications), capture them verbatim. These are REQUIREMENTS, not implementation details -- they must be preserved through the entire planning process and appear in the final plan.
+   - **Reference document collection**: Throughout this conversation, if the user mentions or provides paths to additional documents (brainstorm docs, design docs, specification docs, or any other reference files), attempt to read each path using the Read tool. If the file exists, append its path to REFERENCE_DOCUMENTS. Confirm to the user: "Added {path} to reference documents." At the end of Phase 1, present the full REFERENCE_DOCUMENTS list to the user for confirmation.
 5. Collaboratively define **user stories** at the feature level -- the positive outcomes users should experience.
    - Format: "As a [role], I can [action], so that [benefit]"
    - Each story should describe a concrete, testable outcome from the user's perspective
@@ -337,12 +344,18 @@ Once the plan passes validation, save it using FOB-state-context patterns:
      date: {current date}
      plan-type: phased
      phases: {count}
+     reference-documents:
+       - {path1}
+       - {path2}
      ---
      ```
-     If IS_RE_ENGINEERING is true, add this field to the frontmatter (after `phases`):
+     The `reference-documents` field lists all paths from REFERENCE_DOCUMENTS. If REFERENCE_DOCUMENTS is empty, omit the `reference-documents` field entirely.
+
+     If IS_RE_ENGINEERING is true, ALSO add this field to the frontmatter (after `reference-documents`):
      ```
      source-feature-doc: {FEATURE_DOC_PATH}
      ```
+     This preserves backward compatibility. The feature doc path appears in BOTH `reference-documents` and `source-feature-doc`.
    - Followed by the eight-section plan content
    - If IS_RE_ENGINEERING is true, add a note at the end of the "Task Overview" section (section 1 of the plan):
      "This plan is based on a reverse-engineered feature document: `{FEATURE_DOC_PATH}` (source repo: {SOURCE_REPO}, analysis depth: {ANALYSIS_DEPTH})."

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.2.0",
+  "version": "1.2.1",
   "presets": {
     "coding": {
       "description": "Research-driven coding workflow",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-fob",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Deploy research-driven AI coding assistant assets (skills, agents, commands) into your projects",
   "bin": {
     "ai-fob": "bin/install.js"