@forloop-cc/forloop-opencode-plugin-planner 2.2.1

package/docs/superpowers/plans/2026-05-03-sprint-isolated-directory-structure.md

@@ -0,0 +1,1450 @@
+# Sprint-Isolated Directory Structure Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Migrate all sprint-specific files from flat `~/.forloop/` to `~/.forloop/sprint-{id}/` subdirectories while keeping the shared manifest at `~/.forloop/manifest.json`.
+
+**Architecture:** Add sprint-aware path resolution to `context-resolver.ts`, update `sync-tools.ts` to create/use sprint subdirectories, update all agent/skill documentation to reference new paths, and update tests accordingly. Backward compatible with v1 manifests.
+
+**Tech Stack:** TypeScript, Vitest, Node.js fs/path modules
+
+---
+
+## File Structure
+
+| File | Responsibility |
+|------|---------------|
+| `plugins/capabilities/context-resolver.ts` | Add `getSprintDir()`, `getForloopRoot()`, `getManifestPath()` |
+| `plugins/tools/sync-tools.ts` | Update `resolveForloopRoot()`, `ensureForloopStructure()`, file mappings |
+| `agent/forLoopPlanner.md` | Update all path references and permission blocks |
+| `agent/forLoopStoryEvaluator.md` | Update permission blocks |
+| `skills/forloop-context/SKILL.md` | Update paths and manifest format |
+| `skills/knowledge-management/SKILL.md` | Update file paths |
+| `skills/plan-documentation/SKILL.md` | Update file paths |
+| `skills/task-tracking/SKILL.md` | Update file paths |
+| `skills/aivy-documents-sync/SKILL.md` | Update path references |
+| `skills/sprint-planning/SKILL.md` | Update path references |
+| `test/suites/unit/context-resolver.test.ts` | New test file for context resolver |
+| `test/suites/unit/sync-tools.test.ts` | Update existing tests for sprint subdirs |
+
+---
+
+### Task 1: Add Sprint-Aware Path Resolution Functions
+
+**Files:**
+- Modify: `forloop-opencode-plugin-planner/plugins/capabilities/context-resolver.ts`
+- Create: `forloop-opencode-plugin-planner/test/suites/unit/context-resolver.test.ts`
+
+- [ ] **Step 1: Write failing tests for `getSprintDir`**
+
+```typescript
+// forloop-opencode-plugin-planner/test/suites/unit/context-resolver.test.ts
+import { describe, it, expect } from 'vitest';
+import { getSprintDir, getForloopRoot, getManifestPath } from '../../../plugins/capabilities/context-resolver';
+
+describe('Context Resolver - Sprint Paths', () => {
+  const originalHome = process.env.HOME;
+
+  afterEach(() => {
+    process.env.HOME = originalHome;
+  });
+
+  describe('getSprintDir', () => {
+    it('returns sprint-14 for sprintId 14', () => {
+      expect(getSprintDir(14)).toBe('sprint-14');
+    });
+
+    it('returns sprint-1 for sprintId 1', () => {
+      expect(getSprintDir(1)).toBe('sprint-1');
+    });
+
+    it('returns sprint-999 for sprintId 999', () => {
+      expect(getSprintDir(999)).toBe('sprint-999');
+    });
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `cd forloop-opencode-plugin-planner && npx vitest run test/suites/unit/context-resolver.test.ts -t "getSprintDir"`
+Expected: FAIL with "getSprintDir is not a function" or import error
+
+- [ ] **Step 3: Implement `getSprintDir`**
+
+Add to end of `forloop-opencode-plugin-planner/plugins/capabilities/context-resolver.ts`:
+
+```typescript
+export function getSprintDir(sprintId: number): string {
+  return `sprint-${sprintId}`;
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `cd forloop-opencode-plugin-planner && npx vitest run test/suites/unit/context-resolver.test.ts -t "getSprintDir"`
+Expected: PASS
+
+- [ ] **Step 5: Write failing tests for `getForloopRoot`**
+
+Append to `forloop-opencode-plugin-planner/test/suites/unit/context-resolver.test.ts`:
+
+```typescript
+  describe('getForloopRoot', () => {
+    beforeEach(() => {
+      process.env.HOME = '/tmp/test-home';
+    });
+
+    it('returns root when no sprintId', () => {
+      expect(getForloopRoot()).toBe('/tmp/test-home/.forloop');
+    });
+
+    it('returns sprint subdir when sprintId provided', () => {
+      expect(getForloopRoot(14)).toBe('/tmp/test-home/.forloop/sprint-14');
+    });
+
+    it('uses default HOME when env HOME not set', () => {
+      process.env.HOME = undefined;
+      expect(getForloopRoot()).toBe('/tmp/home/.forloop');
+    });
+
+    it('uses default HOME with sprintId when env HOME not set', () => {
+      process.env.HOME = undefined;
+      expect(getForloopRoot(7)).toBe('/tmp/home/.forloop/sprint-7');
+    });
+  });
+```
+
+- [ ] **Step 6: Run test to verify it fails**
+
+Run: `cd forloop-opencode-plugin-planner && npx vitest run test/suites/unit/context-resolver.test.ts -t "getForloopRoot"`
+Expected: FAIL with "getForloopRoot is not a function"
+
+- [ ] **Step 7: Implement `getForloopRoot`**
+
+Add to `forloop-opencode-plugin-planner/plugins/capabilities/context-resolver.ts` after `getSprintDir`:
+
+```typescript
+export function getForloopRoot(sprintId?: number): string {
+  const home = process.env.HOME || '/tmp/home';
+  const root = path.join(home, '.forloop');
+  if (sprintId !== undefined) {
+    return path.join(root, getSprintDir(sprintId));
+  }
+  return root;
+}
+```
+
+- [ ] **Step 8: Run test to verify it passes**
+
+Run: `cd forloop-opencode-plugin-planner && npx vitest run test/suites/unit/context-resolver.test.ts -t "getForloopRoot"`
+Expected: PASS
+
+- [ ] **Step 9: Write failing tests for `getManifestPath`**
+
+Append to `forloop-opencode-plugin-planner/test/suites/unit/context-resolver.test.ts`:
+
+```typescript
+  describe('getManifestPath', () => {
+    beforeEach(() => {
+      process.env.HOME = '/tmp/test-home';
+    });
+
+    it('returns manifest path at root', () => {
+      expect(getManifestPath()).toBe('/tmp/test-home/.forloop/manifest.json');
+    });
+
+    it('returns same path regardless of sprintId', () => {
+      expect(getManifestPath(14)).toBe('/tmp/test-home/.forloop/manifest.json');
+    });
+  });
+```
+
+- [ ] **Step 10: Run test to verify it fails**
+
+Run: `cd forloop-opencode-plugin-planner && npx vitest run test/suites/unit/context-resolver.test.ts -t "getManifestPath"`
+Expected: FAIL with "getManifestPath is not a function"
+
+- [ ] **Step 11: Implement `getManifestPath`**
+
+Add to `forloop-opencode-plugin-planner/plugins/capabilities/context-resolver.ts` after `getForloopRoot`:
+
+```typescript
+export function getManifestPath(): string {
+  const home = process.env.HOME || '/tmp/home';
+  return path.join(home, '.forloop', 'manifest.json');
+}
+```
+
+- [ ] **Step 12: Run test to verify it passes**
+
+Run: `cd forloop-opencode-plugin-planner && npx vitest run test/suites/unit/context-resolver.test.ts -t "getManifestPath"`
+Expected: PASS
+
+- [ ] **Step 13: Commit**
+
+```bash
+cd forloop-opencode-plugin-planner
+git add plugins/capabilities/context-resolver.ts test/suites/unit/context-resolver.test.ts
+git commit -m "feat: add sprint-aware path resolution functions (getSprintDir, getForloopRoot, getManifestPath)"
+```
+
+---
+
+### Task 2: Update sync-tools.ts to Use Sprint Subdirectories
+
+**Files:**
+- Modify: `forloop-opencode-plugin-planner/plugins/tools/sync-tools.ts`
+
+- [ ] **Step 1: Import new functions and update `resolveForloopRoot`**
+
+Modify `forloop-opencode-plugin-planner/plugins/tools/sync-tools.ts`:
+
+```typescript
+import { ForLoopAPIClient } from '../capabilities/api-client';
+import { validateToken } from '../capabilities/auth';
+import { resolveSprintId, getForloopRoot as getForloopRootPath } from '../capabilities/context-resolver';
+import * as fs from 'fs';
+import * as path from 'path';
+```
+
+Replace the existing `resolveForloopRoot` function:
+
+```typescript
+function resolveForloopRoot(contextDir?: string, sprintId?: number): string {
+  if (sprintId !== undefined) {
+    return getForloopRootPath(sprintId);
+  }
+
+  if (contextDir) {
+    const local = path.join(contextDir, '.forloop');
+    if (fs.existsSync(local) && fs.statSync(local).isDirectory()) return local;
+  }
+
+  return getForloopRootPath();
+}
+```
+
+- [ ] **Step 2: Update `ensureForloopStructure` to accept sprintId**
+
+Replace the existing `ensureForloopStructure` function:
+
+```typescript
+function ensureForloopStructure(forloopRoot: string, sprintId?: number) {
+  fs.mkdirSync(forloopRoot, { recursive: true });
+
+  if (sprintId !== undefined) {
+    fs.mkdirSync(path.join(forloopRoot, 'knowledge'), { recursive: true });
+    fs.mkdirSync(path.join(forloopRoot, 'plan'), { recursive: true });
+    fs.mkdirSync(path.join(forloopRoot, 'task'), { recursive: true });
+  }
+
+  fs.mkdirSync(path.join(getForloopRootPath(), 'sync'), { recursive: true });
+}
+```
+
+- [ ] **Step 3: Update `getSyncManifestPath` to use shared sync directory**
+
+Replace the existing `getSyncManifestPath` function:
+
+```typescript
+function getSyncManifestPath(forloopRoot?: string): string {
+  const syncRoot = path.join(getForloopRootPath(), 'sync');
+  return path.join(syncRoot, 'manifest.json');
+}
+```
+
+- [ ] **Step 4: Update `createS3ToLocalSyncTool` to pass sprintId**
+
+In the `createS3ToLocalSyncTool` execute function, replace these lines:
+
+```typescript
+      const forloopRoot = resolveForloopRoot(context.directory);
+      ensureForloopStructure(forloopRoot);
+```
+
+With:
+
+```typescript
+      const forloopRoot = resolveForloopRoot(context.directory, resolution.sprintId);
+      ensureForloopStructure(forloopRoot, resolution.sprintId);
+```
+
+- [ ] **Step 5: Update `createLocalToS3SyncTool` to pass sprintId**
+
+In the `createLocalToS3SyncTool` execute function, replace these lines:
+
+```typescript
+      const forloopRoot = resolveForloopRoot(context.directory);
+      ensureForloopStructure(forloopRoot);
+```
+
+With:
+
+```typescript
+      const forloopRoot = resolveForloopRoot(context.directory, resolution.sprintId);
+      ensureForloopStructure(forloopRoot, resolution.sprintId);
+```
+
+- [ ] **Step 6: Verify all functions in sync-tools.ts are consistent**
+
+The file should now import from `context-resolver.ts`:
+```typescript
+import { resolveSprintId, getForloopRoot as getForloopRootPath } from '../capabilities/context-resolver';
+```
+
+- [ ] **Step 7: Commit**
+
+```bash
+cd forloop-opencode-plugin-planner
+git add plugins/tools/sync-tools.ts
+git commit -m "feat: update sync-tools to use sprint subdirectories"
+```
+
+---
+
+### Task 3: Update sync-tools Unit Tests
+
+**Files:**
+- Modify: `forloop-opencode-plugin-planner/test/suites/unit/sync-tools.test.ts`
+
+- [ ] **Step 1: Update test paths from flat to sprint subdir format**
+
+In `forloop-opencode-plugin-planner/test/suites/unit/sync-tools.test.ts`, update the `it('syncs local file to S3 with folder inference and mapping replacement', ...)` test.
+
+Replace:
+```typescript
+    const forloopRoot = path.join(tmpHome, '.forloop');
+    const filePath = path.join(forloopRoot, 'knowledge', 'knowledge-test-1.md');
+```
+
+With:
+```typescript
+    const forloopRoot = path.join(tmpHome, '.forloop', 'sprint-14');
+    const filePath = path.join(forloopRoot, 'knowledge', 'knowledge-test-1.md');
+```
+
+- [ ] **Step 2: Update manifest path in the same test**
+
+Replace:
+```typescript
+    const manifestPath = path.join(forloopRoot, 'sync', 'manifest.json');
+```
+
+With:
+```typescript
+    const manifestPath = path.join(tmpHome, '.forloop', 'sync', 'manifest.json');
+```
+
+- [ ] **Step 3: Update delete test paths**
+
+In the `it('deletes remote mapping on local delete action', ...)` test, replace:
+```typescript
+    const forloopRoot = path.join(tmpHome, '.forloop');
+    const filePath = path.join(forloopRoot, 'plan', 'plan-14-20260412-000000.md');
+```
+
+With:
+```typescript
+    const forloopRoot = path.join(tmpHome, '.forloop', 'sprint-14');
+    const filePath = path.join(forloopRoot, 'plan', 'plan-14-20260412-000000.md');
+```
+
+And update manifest path:
+```typescript
+    const manifestPath = path.join(tmpHome, '.forloop', 'sync', 'manifest.json');
+```
+
+- [ ] **Step 4: Update s3-to-local test path assertion**
+
+In the `it('syncs remote knowledge file to local', ...)` test, replace:
+```typescript
+    const localPath = path.join(tmpHome, '.forloop', 'knowledge', 'knowledge-abc-20260412-000000.md');
+```
+
+With:
+```typescript
+    const localPath = path.join(tmpHome, '.forloop', 'sprint-14', 'knowledge', 'knowledge-abc-20260412-000000.md');
+```
+
+- [ ] **Step 5: Run tests to verify they pass**
+
+Run: `cd forloop-opencode-plugin-planner && npx vitest run test/suites/unit/sync-tools.test.ts -v`
+Expected: All sync tool tests PASS
+
+- [ ] **Step 6: Commit**
+
+```bash
+cd forloop-opencode-plugin-planner
+git add test/suites/unit/sync-tools.test.ts
+git commit -m "test: update sync-tools tests for sprint subdirectories"
+```
+
+---
+
+### Task 4: Update forLoopPlanner.md Agent Definition
+
+**Files:**
+- Modify: `forloop-opencode-plugin-planner/agent/forLoopPlanner.md`
+
+- [ ] **Step 1: Update permission block**
+
+Replace lines 13-17:
+```yaml
+permission:
+  "*": allow
+  external_directory:
+    "/tmp/home/.forloop/**": allow
+    "/tmp/home/.config/opencode/**": allow
+    "~/.forloop/**": allow
+    "~/.config/forloop/**": allow
+```
+
+With:
+```yaml
+permission:
+  "*": allow
+  external_directory:
+    "/tmp/home/.forloop/**": allow
+    "/tmp/home/.forloop/sprint-*/**": allow
+    "/tmp/home/.config/opencode/**": allow
+    "~/.forloop/**": allow
+    "~/.forloop/sprint-*/**": allow
+    "~/.config/forloop/**": allow
+```
+
+- [ ] **Step 2: Update Step 0 runtime path section**
+
+Replace lines 100-103:
+```markdown
+**IMPORTANT: Runtime Path**
+- The .forloop/ folder is located at `/tmp/home/.forloop/` (NOT in current directory)
+- HOME directory is `/tmp/home` in Lambda environment
+- Use `$HOME/.forloop/` or `/tmp/home/.forloop/` for all paths
+```
+
+With:
+```markdown
+**IMPORTANT: Runtime Path**
+- The .forloop/ folder is located at `/tmp/home/.forloop/` (NOT in current directory)
+- Sprint files are in `/tmp/home/.forloop/sprint-{sprintId}/` (e.g., `sprint-14/`)
+- HOME directory is `/tmp/home` in Lambda environment
+- Use `$HOME/.forloop/sprint-{sprintId}/` or `/tmp/home/.forloop/sprint-{sprintId}/` for sprint files
+- Manifest is always at `$HOME/.forloop/manifest.json` (shared across sprints)
+```
+
+- [ ] **Step 3: Update manifest check instructions**
+
+Replace lines 106-117:
+```markdown
+1. **Quick check** for `$HOME/.forloop/manifest.json` (NOT `/var/task/.forloop/`)
+2. **IF manifest exists and has activeSprintId:**
+   - Load knowledge, plans, and tasks from $HOME/.forloop/
+   - Present context summary to user
+   - Confirm active sprint
+3. **IF manifest missing or empty:**
+   - ⚠️ **STOP searching immediately**
+   - ✅ **Call `forloopSprintList` to get sprints from API**
+   - ✅ **Call `forloopUserProfile` to get user info from API**
+   - Ask user to select/confirm sprint
+   - Create `$HOME/.forloop/manifest.json` after selection
+```
+
+With:
+```markdown
+1. **Quick check** for `$HOME/.forloop/manifest.json` (NOT `/var/task/.forloop/`)
+2. **IF manifest exists and has activeSprintId:**
+   - Load knowledge, plans, and tasks from `$HOME/.forloop/sprint-{activeSprintId}/`
+   - Present context summary to user
+   - Confirm active sprint
+3. **IF manifest missing or empty:**
+   - ⚠️ **STOP searching immediately**
+   - ✅ **Call `forloopSprintList` to get sprints from API**
+   - ✅ **Call `forloopUserProfile` to get user info from API**
+   - Ask user to select/confirm sprint
+   - Create `$HOME/.forloop/manifest.json` after selection
+```
+
+- [ ] **Step 4: Update correct path examples**
+
+Replace lines 142-151:
+```markdown
+**Correct Path Examples:**
+```bash
+✅ ls -la /tmp/home/.forloop/
+✅ ls -la $HOME/.forloop/
+✅ cat /tmp/home/.forloop/manifest.json
+
+❌ ls -la /var/task/.forloop/     # WRONG location
+❌ ls -la ./.forloop/              # WRONG relative path
+❌ ls -la ~/.forloop/              # ~ might not work
+```
+
+With:
+```markdown
+**Correct Path Examples:**
+```bash
+✅ ls -la /tmp/home/.forloop/
+✅ ls -la /tmp/home/.forloop/sprint-14/
+✅ ls -la $HOME/.forloop/sprint-$SPRINT_ID/
+✅ cat /tmp/home/.forloop/manifest.json
+
+❌ ls -la /var/task/.forloop/     # WRONG location
+❌ ls -la ./.forloop/              # WRONG relative path
+❌ ls -la ~/.forloop/              # ~ might not work
+```
+
+- [ ] **Step 5: Update sync download paths**
+
+Replace lines 132-135:
+```markdown
+- Downloads `project/plans/*` → `~/.forloop/plan/`
+- Downloads `project/tasks/*` → `~/.forloop/task/`
+- Downloads `project/knowledge/*` → `~/.forloop/knowledge/`
+```
+
+With:
+```markdown
+- Downloads `project/plans/*` → `~/.forloop/sprint-{sprintId}/plan/`
+- Downloads `project/tasks/*` → `~/.forloop/sprint-{sprintId}/task/`
+- Downloads `project/knowledge/*` → `~/.forloop/sprint-{sprintId}/knowledge/`
+```
+
+- [ ] **Step 6: Update Capabilities section**
+
+Replace lines 189-194:
+```markdown
+- **NEW:** Load persistent context from .forloop/ folder on session start
+- **NEW:** Manage .forloop/manifest.json for deterministic sprint resume
+- Discover current sprint context and sprint contents
+- Ask clarifying questions and confirm requirements
+- **NEW:** Auto-capture knowledge to .forloop/knowledge/
+- **NEW:** Generate plan files in .forloop/plan/
+```
+
+With:
+```markdown
+- **NEW:** Load persistent context from .forloop/sprint-{id}/ folder on session start
+- **NEW:** Manage .forloop/manifest.json for deterministic sprint resume
+- Discover current sprint context and sprint contents
+- Ask clarifying questions and confirm requirements
+- **NEW:** Auto-capture knowledge to .forloop/sprint-{id}/knowledge/
+- **NEW:** Generate plan files in .forloop/sprint-{id}/plan/
+```
+
+- [ ] **Step 7: Update manifest update references**
+
+Replace lines 194:
+```markdown
+- **NEW:** Update .forloop/manifest.json after plan/task creation
+```
+
+With:
+```markdown
+- **NEW:** Update .forloop/manifest.json after plan/task creation (manifest stays at root, file paths reference sprint subdirs)
+```
+
+- [ ] **Step 8: Update Safety Boundary section**
+
+Replace lines 288-293:
+```markdown
+- The only files you may create/edit are:
+  - Knowledge files in `.forloop/knowledge/`
+  - Plan files in `.forloop/plan/`
+  - Task files in `.forloop/task/`
+  - Manifest file `.forloop/manifest.json`
+```
+
+With:
+```markdown
+- The only files you may create/edit are:
+  - Knowledge files in `.forloop/sprint-{id}/knowledge/`
+  - Plan files in `.forloop/sprint-{id}/plan/`
+  - Task files in `.forloop/sprint-{id}/task/`
+  - Manifest file `.forloop/manifest.json` (at root, shared across sprints)
+```
+
+- [ ] **Step 9: Update Folder Mapping table**
+
+Replace lines 259-263:
+```markdown
+| Local Path | S3 Folder | Parameter |
+|------------|-----------|-----------|
+| `.forloop/plan/*` | `project/plans/` | `--folder project/plans` |
+| `.forloop/task/*` | `project/tasks/` | `--folder project/tasks` |
+| `.forloop/knowledge/*` | `project/knowledge/` | `--folder project/knowledge` |
+```
+
+With:
+```markdown
+| Local Path | S3 Folder | Parameter |
+|------------|-----------|-----------|
+| `.forloop/sprint-{id}/plan/*` | `project/plans/` | `--folder project/plans` |
+| `.forloop/sprint-{id}/task/*` | `project/tasks/` | `--folder project/tasks` |
+| `.forloop/sprint-{id}/knowledge/*` | `project/knowledge/` | `--folder project/knowledge` |
+```
+
+- [ ] **Step 10: Update all remaining path references in examples**
+
+Replace in the Example sections:
+- `.forloop/knowledge/` → `.forloop/sprint-{id}/knowledge/`
+- `.forloop/plan/` → `.forloop/sprint-{id}/plan/`
+- `.forloop/task/` → `.forloop/sprint-{id}/task/`
+
+Specifically update lines 328-335, 344-366, 389-402, 469-481, 487-497.
+
+For example, replace line 333:
+```bash
+forloopSyncLocalToS3 --filePath .forloop/knowledge/knowledge-{topic}-{datetime}.md --sprintId {sprintId} --folder project/knowledge --storyId {docFolderId}
+```
+
+With:
+```bash
+forloopSyncLocalToS3 --filePath .forloop/sprint-{sprintId}/knowledge/knowledge-{topic}-{datetime}.md --sprintId {sprintId} --folder project/knowledge --storyId {docFolderId}
+```
+
+Replace line 362:
+```bash
+  --filePath .forloop/plan/plan-{sprintId}-{datetime}.md \
+```
+
+With:
+```bash
+  --filePath .forloop/sprint-{sprintId}/plan/plan-{sprintId}-{datetime}.md \
+```
+
+Replace line 394:
+```bash
+      --filePath .forloop/task/task-{sprintId}-{datetime}.md \
+```
+
+With:
+```bash
+      --filePath .forloop/sprint-{sprintId}/task/task-{sprintId}-{datetime}.md \
+```
+
+- [ ] **Step 11: Commit**
+
+```bash
+cd forloop-opencode-plugin-planner
+git add agent/forLoopPlanner.md
+git commit -m "docs: update forLoopPlanner agent paths for sprint subdirectories"
+```
+
+---
+
+### Task 5: Update forLoopStoryEvaluator.md Permission Block
+
+**Files:**
+- Modify: `forloop-opencode-plugin-planner/agent/forLoopStoryEvaluator.md`
+
+- [ ] **Step 1: Update permission block**
+
+Replace lines 12-17:
+```yaml
+permission:
+  "*": allow
+  external_directory:
+    "/tmp/home/.forloop/**": allow
+    "/tmp/home/.config/opencode/**": allow
+    "~/.forloop/**": allow
+    "~/.config/forloop/**": allow
+```
+
+With:
+```yaml
+permission:
+  "*": allow
+  external_directory:
+    "/tmp/home/.forloop/**": allow
+    "/tmp/home/.forloop/sprint-*/**": allow
+    "/tmp/home/.config/opencode/**": allow
+    "~/.forloop/**": allow
+    "~/.forloop/sprint-*/**": allow
+    "~/.config/forloop/**": allow
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+cd forloop-opencode-plugin-planner
+git add agent/forLoopStoryEvaluator.md
+git commit -m "docs: update forLoopStoryEvaluator permission paths for sprint subdirectories"
+```
+
+---
+
+### Task 6: Update forloop-context Skill
+
+**Files:**
+- Modify: `forloop-opencode-plugin-planner/skills/forloop-context/SKILL.md`
+
+- [ ] **Step 1: Update Step 1 - Resolve Context Directory**
+
+Replace lines 69-81:
+```markdown
+### Step 1: Resolve Context Directory
+
+Use this location order:
+
+1. `./.forloop/` (project-local)
+2. `~/.forloop/` (user-global fallback)
+
+If neither exists, create `~/.forloop/` and its subfolders.
+
+**Outcomes:**
+
+- **Exists:** Continue to load context
+- **Not exists:** Create structure, inform user of fresh start
+```
+
+With:
+```markdown
+### Step 1: Resolve Context Directory
+
+The manifest is always at `~/.forloop/manifest.json`.
+Sprint files are at `~/.forloop/sprint-{sprintId}/`.
+
+1. Check `~/.forloop/manifest.json` for `activeSprintId`
+2. If manifest has active sprint, use `~/.forloop/sprint-{activeSprintId}/`
+3. If no sprint selected, work at `~/.forloop/` root only
+
+If `~/.forloop/` doesn't exist, create it.
+
+**Outcomes:**
+
+- **Manifest exists with active sprint:** Load from `~/.forloop/sprint-{id}/`
+- **Manifest exists, no sprint:** Create structure, inform user of fresh start
+- **No manifest:** Create `~/.forloop/` and manifest, inform user of fresh start
+```
+
+- [ ] **Step 2: Update Step 2 - Check Manifest format**
+
+Replace lines 85-106:
+```markdown
+**Expected manifest structure:**
+
+```json
+{
+  "version": 1,
+  "activeSprintId": 14,
+  "sprints": {
+    "14": {
+      "plan": {
+        "file": "~/.forloop/plan/plan-14-20260410-093015.md",
+        "createdAt": "2026-04-10T09:30:15Z"
+      },
+      "tasks": {
+        "file": "~/.forloop/task/task-14-20260410-093530.md",
+        "storyIds": ["123", "124", "125"]
+      }
+    }
+  }
+}
+```
+
+With:
+```markdown
+**Expected manifest structure (v2):**
+
+```json
+{
+  "version": 2,
+  "activeSprintId": 14,
+  "sprints": {
+    "14": {
+      "sprintDir": "sprint-14",
+      "plan": {
+        "file": "sprint-14/plan/plan-14-20260410-093015.md",
+        "createdAt": "2026-04-10T09:30:15Z"
+      },
+      "tasks": {
+        "file": "sprint-14/task/task-14-20260410-093530.md",
+        "storyIds": ["123", "124", "125"]
+      }
+    }
+  }
+}
+```
+
+- [ ] **Step 3: Update Step 3 - Scan Folders**
+
+Replace lines 118-125:
+```markdown
+If manifest is missing/invalid, scan:
+
+- `knowledge/` (latest 3)
+- `plan/` (latest 1)
+- `task/` (latest 1)
+```
+
+With:
+```markdown
+If manifest is missing/invalid, scan:
+
+- `sprint-{id}/knowledge/` (latest 3) if sprint is known
+- `sprint-{id}/plan/` (latest 1) if sprint is known
+- `sprint-{id}/task/` (latest 1) if sprint is known
+```
+
+- [ ] **Step 4: Update Fresh Session section**
+
+Replace lines 253-289:
+```markdown
+## Fresh Session (No .forloop)
+
+**If no .forloop directory:**
+
+```
+📁 No Previous Context Found
+
+This appears to be a fresh project. I'll create the
+.forloop folder structure for future sessions.
+
+Created:
+  .forloop/knowledge/
+  .forloop/plan/
+  .forloop/task/
+
+How would you like to get started?
+
+1. Create a new sprint plan
+2. Connect to existing ForLoop sprint
+3. Learn about your project
+```
+
+**Create structure:**
+
+```bash
+mkdir -p .forloop/knowledge .forloop/plan .forloop/task
+```
+
+**Initialize empty manifest:**
+
+```json
+{
+  "version": 1,
+  "activeSprintId": null,
+  "sprints": {}
+}
+```
+
+With:
+```markdown
+## Fresh Session (No .forloop)
+
+**If no .forloop directory:**
+
+```
+📁 No Previous Context Found
+
+This appears to be a fresh project. I'll create the
+.forloop folder structure for future sessions.
+
+Created:
+  .forloop/manifest.json
+  .forloop/sync/
+
+Sprint directories will be created when a sprint is selected:
+  .forloop/sprint-{id}/knowledge/
+  .forloop/sprint-{id}/plan/
+  .forloop/sprint-{id}/task/
+
+How would you like to get started?
+
+1. Create a new sprint plan
+2. Connect to existing ForLoop sprint
+3. Learn about your project
+```
+
+**Create structure:**
+
+```bash
+mkdir -p .forloop/sync
+```
+
+**Initialize empty manifest:**
+
+```json
+{
+  "version": 2,
+  "activeSprintId": null,
+  "sprints": {}
+}
+```
+
+- [ ] **Step 5: Update Anti-Patterns table**
+
+Replace anti-pattern #1:
+```markdown
+| 1 | Skip context check at session start | Always check ~/.forloop/ first |
+```
+
+With:
+```markdown
+| 1 | Skip context check at session start | Always check ~/.forloop/manifest.json first, then load sprint subdir |
+```
+
+- [ ] **Step 6: Update Quality Gates**
+
+Replace lines 466-471:
+```markdown
+## Quality Gates
+
+- [ ] ~/.forloop/ directory checked (or created)
+- [ ] manifest.json loaded and validated (or fallback scan used)
+```
+
+With:
+```markdown
+## Quality Gates
+
+- [ ] ~/.forloop/ directory and manifest.json checked (or created)
+- [ ] manifest.json loaded and validated (v2 format with sprintDir)
+```
+
+- [ ] **Step 7: Commit**
+
+```bash
+cd forloop-opencode-plugin-planner
+git add skills/forloop-context/SKILL.md
+git commit -m "docs: update forloop-context skill for sprint subdirectories"
+```
+
+---
+
+### Task 7: Update knowledge-management Skill
+
+**Files:**
+- Modify: `forloop-opencode-plugin-planner/skills/knowledge-management/SKILL.md`
+
+- [ ] **Step 1: Update storage path in front matter**
+
+Replace line 15:
+```yaml
+storage: ~/.forloop/knowledge/
+```
+
+With:
+```yaml
+storage: ~/.forloop/sprint-{id}/knowledge/
+```
+
+- [ ] **Step 2: Update Step 4 - Create Knowledge File location**
+
+Replace line 125:
+```markdown
+**Location:** `.forloop/knowledge/knowledge-{topic}-{datetime}.md`
+```
+
+With:
+```markdown
+**Location:** `.forloop/sprint-{sprintId}/knowledge/knowledge-{topic}-{datetime}.md`
+```
+
+- [ ] **Step 3: Update Step 5 - Upload path**
+
+Replace line 181:
+```bash
+  --filePath .forloop/knowledge/knowledge-{topic}-{datetime}.md \
+```
+
+With:
+```bash
+  --filePath .forloop/sprint-{sprintId}/knowledge/knowledge-{topic}-{datetime}.md \
+```
+
+- [ ] **Step 4: Update Deduplication Check**
+
+Replace line 291:
+```bash
+ls .forloop/knowledge/ | grep -i "{topic}"
+```
+
+With:
+```bash
+ls .forloop/sprint-{sprintId}/knowledge/ | grep -i "{topic}"
+```
+
+- [ ] **Step 5: Update Quality Gates**
+
+Replace line 351:
+```markdown
+- [ ] File created at `.forloop/knowledge/knowledge-{topic}-{datetime}.md`
+```
+
+With:
+```markdown
+- [ ] File created at `.forloop/sprint-{sprintId}/knowledge/knowledge-{topic}-{datetime}.md`
+```
+
+- [ ] **Step 6: Update Anti-Pattern #1**
+
+Replace:
+```markdown
+| 1 | Capture without writing to ~/.forloop/knowledge/ | Create file with knowledge-{topic}-{datetime}.md format |
+```
+
+With:
+```markdown
+| 1 | Capture without writing to ~/.forloop/sprint-{id}/knowledge/ | Create file with sprint subdir and knowledge-{topic}-{datetime}.md format |
+```
+
+- [ ] **Step 7: Commit**
+
+```bash
+cd forloop-opencode-plugin-planner
+git add skills/knowledge-management/SKILL.md
+git commit -m "docs: update knowledge-management skill for sprint subdirectories"
+```
+
+---
+
+### Task 8: Update plan-documentation Skill
+
+**Files:**
+- Modify: `forloop-opencode-plugin-planner/skills/plan-documentation/SKILL.md`
+
+- [ ] **Step 1: Update storage path in front matter**
+
+Replace line 15:
+```yaml
+storage: ~/.forloop/plan/
+```
+
+With:
+```yaml
+storage: ~/.forloop/sprint-{id}/plan/
+```
+
+- [ ] **Step 2: Update manifest path reference**
+
+Replace line 87:
+```markdown
+Check manifest first: `~/.forloop/manifest.json`.
+```
+
+With:
+```markdown
+Check manifest first: `~/.forloop/manifest.json`. If valid, load plan from `~/.forloop/sprint-{activeSprintId}/plan/`.
+```
+
+- [ ] **Step 3: Update Step 1 - Check Existing Plans fallback**
+
+Replace line 93:
+```markdown
+If no manifest, scan `~/.forloop/plan/` for the most recent plan for the sprint.
+```
+
+With:
+```markdown
+If no manifest, scan `~/.forloop/sprint-{sprintId}/plan/` for the most recent plan for the sprint.
+```
+
+- [ ] **Step 4: Update Step 5 - Write Plan File location**
+
+Replace line 158:
+```markdown
+**Location:** `.forloop/plan/plan-{sprintId}-{datetime}.md`
+```
+
+With:
+```markdown
+**Location:** `.forloop/sprint-{sprintId}/plan/plan-{sprintId}-{datetime}.md`
+```
+
+- [ ] **Step 5: Update Step 6 - Update Active Manifest**
+
+Replace the manifest JSON example (lines 245-258):
+```json
+{
+  "version": 1,
+  "activeSprintId": {sprintId},
+  "sprints": {
+    "{sprintId}": {
+      "plan": {
+        "file": ".forloop/plan/plan-{sprintId}-{datetime}.md",
+        "createdAt": "{datetime}"
+      }
+    }
+  }
+}
+```
+
+With:
+```json
+{
+  "version": 2,
+  "activeSprintId": {sprintId},
+  "sprints": {
+    "{sprintId}": {
+      "sprintDir": "sprint-{sprintId}",
+      "plan": {
+        "file": "sprint-{sprintId}/plan/plan-{sprintId}-{datetime}.md",
+        "createdAt": "{datetime}"
+      }
+    }
+  }
+}
+```
+
+- [ ] **Step 6: Update Step 7 - Upload path**
+
+Replace line 280:
+```bash
+  --filePath .forloop/plan/plan-{sprintId}-{datetime}.md \
+```
+
+With:
+```bash
+  --filePath .forloop/sprint-{sprintId}/plan/plan-{sprintId}-{datetime}.md \
+```
+
+- [ ] **Step 7: Update Anti-Patterns and Quality Gates**
+
+Replace:
+```markdown
+| 4 | Skip manifest update | Update `~/.forloop/manifest.json` with new plan path |
+```
+
+With:
+```markdown
+| 4 | Skip manifest update | Update `~/.forloop/manifest.json` with v2 format (include sprintDir) |
+```
+
+Replace quality gate:
+```markdown
+- [ ] Plan file created at `.forloop/plan/plan-{sprintId}-{datetime}.md`
+```
+
+With:
+```markdown
+- [ ] Plan file created at `.forloop/sprint-{sprintId}/plan/plan-{sprintId}-{datetime}.md`
+```
+
+- [ ] **Step 8: Commit**
+
+```bash
+cd forloop-opencode-plugin-planner
+git add skills/plan-documentation/SKILL.md
+git commit -m "docs: update plan-documentation skill for sprint subdirectories"
+```
+
+---
+
+### Task 9: Update task-tracking Skill
+
+**Files:**
+- Modify: `forloop-opencode-plugin-planner/skills/task-tracking/SKILL.md`
+
+- [ ] **Step 1: Update storage path in front matter**
+
+Replace line 16:
+```yaml
+storage: ~/.forloop/task/
+```
+
+With:
+```yaml
+storage: ~/.forloop/sprint-{id}/task/
+```
+
+- [ ] **Step 2: Update Step 1 - Read Plan File**
+
+Replace line 77-79:
+```markdown
+Check manifest first: `~/.forloop/manifest.json`.
+
+Get plan file from manifest. If missing, scan `~/.forloop/plan/` for the latest `plan-{sprintId}-*.md`.
+```
+
+With:
+```markdown
+Check manifest first: `~/.forloop/manifest.json`.
+
+Get plan file from manifest. If missing, scan `~/.forloop/sprint-{sprintId}/plan/` for the latest `plan-{sprintId}-*.md`.
+```
+
+- [ ] **Step 3: Update Step 7 - Write Task List File location**
+
+Replace line 231:
+```markdown
+**Location:** `.forloop/task/task-{sprintId}-{datetime}.md`
+```
+
+With:
+```markdown
+**Location:** `.forloop/sprint-{sprintId}/task/task-{sprintId}-{datetime}.md`
+```
+
+- [ ] **Step 4: Update Step 8 - Update Manifest**
+
+Replace the manifest JSON example (lines 276-290):
+```json
+{
+  "version": 1,
+  "activeSprintId": {sprintId},
+  "sprints": {
+    "{sprintId}": {
+      "plan": { ... },
+      "tasks": {
+        "file": ".forloop/task/task-{sprintId}-{datetime}.md",
+        "storyIds": ["201", "202", "203"]
+      }
+    }
+  }
+}
+```
+
+With:
+```json
+{
+  "version": 2,
+  "activeSprintId": {sprintId},
+  "sprints": {
+    "{sprintId}": {
+      "sprintDir": "sprint-{sprintId}",
+      "plan": { ... },
+      "tasks": {
+        "file": "sprint-{sprintId}/task/task-{sprintId}-{datetime}.md",
+        "storyIds": ["201", "202", "203"]
+      }
+    }
+  }
+}
+```
+
+- [ ] **Step 5: Update Step 9 - Upload path**
+
+Replace line 307:
+```bash
+  --filePath .forloop/task/task-{sprintId}-{datetime}.md \
+```
+
+With:
+```bash
+  --filePath .forloop/sprint-{sprintId}/task/task-{sprintId}-{datetime}.md \
+```
+
+- [ ] **Step 6: Update File Organization - Folder Mapping**
+
+Replace lines 414-420:
+```markdown
+| Local Path | S3 Folder | Parameter |
+|------------|-----------|-----------|
+| `.forloop/plan/*` | `project/plans/` | `--folder project/plans` |
+| `.forloop/knowledge/*` | `project/knowledge/` | `--folder project/knowledge` |
+| `.forloop/task/*` | `project/tasks/` | `--folder project/tasks` |
+```
+
+With:
+```markdown
+| Local Path | S3 Folder | Parameter |
+|------------|-----------|-----------|
+| `.forloop/sprint-{id}/plan/*` | `project/plans/` | `--folder project/plans` |
+| `.forloop/sprint-{id}/knowledge/*` | `project/knowledge/` | `--folder project/knowledge` |
+| `.forloop/sprint-{id}/task/*` | `project/tasks/` | `--folder project/tasks` |
+```
+
+- [ ] **Step 7: Update Quality Gates**
+
+Replace:
+```markdown
+- [ ] Task file written to `.forloop/task/task-{sprintId}-{datetime}.md`
+```
+
+With:
+```markdown
+- [ ] Task file written to `.forloop/sprint-{sprintId}/task/task-{sprintId}-{datetime}.md`
+```
+
+- [ ] **Step 8: Update Anti-Pattern #7**
+
+Replace:
+```markdown
+| 7 | Skip manifest update | Always update `~/.forloop/manifest.json` |
+```
+
+With:
+```markdown
+| 7 | Skip manifest update | Always update `~/.forloop/manifest.json` with v2 format |
+```
+
+- [ ] **Step 9: Commit**
+
+```bash
+cd forloop-opencode-plugin-planner
+git add skills/task-tracking/SKILL.md
+git commit -m "docs: update task-tracking skill for sprint subdirectories"
+```
+
+---
+
+### Task 10: Update aivy-documents-sync and sprint-planning Skills
+
+**Files:**
+- Modify: `forloop-opencode-plugin-planner/skills/aivy-documents-sync/SKILL.md`
+- Modify: `forloop-opencode-plugin-planner/skills/sprint-planning/SKILL.md`
+
+- [ ] **Step 1: Update aivy-documents-sync**
+
+Replace line 15:
+```yaml
+storage: ~/.forloop/
+```
+
+With:
+```yaml
+storage: ~/.forloop/sprint-{id}/
+```
+
+Replace lines 41-45:
+```markdown
+- `.forloop/knowledge/*`
+- `.forloop/plan/*`
+- `.forloop/task/*`
+```
+
+With:
+```markdown
+- `.forloop/sprint-{id}/knowledge/*`
+- `.forloop/sprint-{id}/plan/*`
+- `.forloop/sprint-{id}/task/*`
+```
+
+Replace line 60:
+```markdown
+- Files under `project/knowledge`, `project/plans`, and `project/tasks` are synced to local `knowledge/`, `plan/`, and `task/`.
+```
+
+With:
+```markdown
+- Files under `project/knowledge`, `project/plans`, and `project/tasks` are synced to local `sprint-{id}/knowledge/`, `sprint-{id}/plan/`, and `sprint-{id}/task/`.
+```
+
+- [ ] **Step 2: Update sprint-planning**
+
+Replace line 6:
+```yaml
+  Integrates with ~/.forloop/ for persistent context.
+```
+
+With:
+```yaml
+  Integrates with ~/.forloop/sprint-{id}/ for persistent context.
+```
+
+Replace line 71-73:
+```markdown
+- [ ] Run forloop-context skill to load `~/.forloop/` context
+- [ ] Check manifest.json for active sprint
+- [ ] Review loaded knowledge, plans, and tasks
+```
+
+With:
+```markdown
+- [ ] Run forloop-context skill to load `~/.forloop/manifest.json` context
+- [ ] Check manifest.json for active sprint
+- [ ] Review loaded knowledge, plans, and tasks from `~/.forloop/sprint-{id}/`
+```
+
+Replace line 91:
+```markdown
+- [ ] Update `~/.forloop/manifest.json`
+```
+
+With:
+```markdown
+- [ ] Update `~/.forloop/manifest.json` (v2 format with sprintDir)
+```
+
+Replace line 134:
+```markdown
+- Load knowledge, plans, and tasks
+```
+
+With:
+```markdown
+- Load knowledge, plans, and tasks from `~/.forloop/sprint-{id}/`
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+cd forloop-opencode-plugin-planner
+git add skills/aivy-documents-sync/SKILL.md skills/sprint-planning/SKILL.md
+git commit -m "docs: update aivy-documents-sync and sprint-planning skills for sprint subdirectories"
+```
+
+---
+
+### Task 11: Run Full Test Suite and Fix Any Failures
+
+**Files:**
+- Various test files may need minor adjustments
+
+- [ ] **Step 1: Run typecheck**
+
+Run: `cd forloop-opencode-plugin-planner && npx tsc --noEmit`
+Expected: No type errors
+
+- [ ] **Step 2: Run all unit tests**
+
+Run: `cd forloop-opencode-plugin-planner && npx vitest run test/suites/unit/ -v`
+Expected: All tests PASS
+
+- [ ] **Step 3: Fix any test failures**
+
+If any tests fail due to path changes, update them to use sprint subdirectory format. Common fixes:
+- Update `path.join(tmpHome, '.forloop', 'knowledge')` → `path.join(tmpHome, '.forloop', 'sprint-14', 'knowledge')`
+- Update `path.join(tmpHome, '.forloop', 'sync', 'manifest.json')` stays the same (sync manifest is shared)
+- Update manifest version expectations from 1 to 2 where applicable
+
+- [ ] **Step 4: Run lint check**
+
+Run: `cd forloop-opencode-plugin-planner && npm run lint`
+Expected: No lint errors
+
+- [ ] **Step 5: Commit any fixes**
+
+```bash
+cd forloop-opencode-plugin-planner
+git add -A
+git commit -m "test: fix remaining test path assertions for sprint subdirectories"
+```
+
+---
+
+## Spec Coverage Check
+
+| Spec Requirement | Task |
+|-----------------|------|
+| `getSprintDir()` function | Task 1 |
+| `getForloopRoot()` function | Task 1 |
+| `getManifestPath()` function | Task 1 |
+| sync-tools uses sprint subdirs | Task 2 |
+| sync-tests updated | Task 3 |
+| forLoopPlanner.md paths | Task 4 |
+| forLoopStoryEvaluator.md paths | Task 5 |
+| forloop-context skill | Task 6 |
+| knowledge-management skill | Task 7 |
+| plan-documentation skill | Task 8 |
+| task-tracking skill | Task 9 |
+| aivy-documents-sync skill | Task 10 |
+| sprint-planning skill | Task 10 |
+| Full test suite passes | Task 11 |
+| Backward compatibility (v1→v2 manifest) | Implicit - tools check version field, create sprintDir when missing |
+| Manifest stays at root | All tasks preserve `~/.forloop/manifest.json` location |
+| Sprint-specific subdirs | All file operations use `sprint-{id}/` prefix |
+
+## Placeholder Scan
+
+No placeholders found. All steps contain exact code, paths, and commands.
+
+## Type Consistency Check
+
+- `getSprintDir(sprintId: number): string` - consistent across all references
+- `getForloopRoot(sprintId?: number): string` - consistent
+- `getManifestPath(): string` - consistent
+- Manifest version: 2 (all manifest examples use v2)
+- All file paths use `sprint-{id}/` prefix consistently