GFramework/ai-plan

AI Plan

ai-plan/ stores AI task recovery artifacts for this repository, but each subdirectory serves a different sharing and bootstrapping purpose.

Directory Semantics

• public/README.md
  • Shared startup index for boot.
  • Maps worktrees or branches to active topics and points at the primary tracking/trace entry paths.
  • Must list only active topics.
• public/<topic>/todos/
  • Repository-safe recovery documents for one active topic.
  • Use these for durable task state that another contributor or worktree may need to resume safely.
• public/<topic>/traces/
  • Repository-safe execution traces for one active topic.
  • Record decisions, validation milestones, and the immediate next step.
• public/<topic>/archive/
  • Stage-level archive for completed artifacts that still belong to an active topic.
  • Use this when a topic remains active, but some prior phase no longer belongs in the default boot path.
  • Prefer archive/todos/ and archive/traces/ when archiving content cut from the active recovery entry files.
• public/archive/<topic>/
  • Completed-topic archive.
  • Move the entire topic directory here when that work direction is fully complete.
• private/
  • Worktree-private recovery space.
  • Use this for temporary notes, local scratch recovery points, or state that only matters in the current worktree.
  • Keep this directory untracked.

Workflow Rules

• boot must read public/README.md first, then the mapped active topic directories, and only then fall back to scanning active topics directly.
• If no mapping exists for the current worktree or branch, scan public/<topic>/ and ignore public/archive/ unless the user explicitly asks for historical context.
• When a worktree changes its active topic set, update public/README.md in the same change.
• When a stage is complete, move the finished artifacts into public/<topic>/archive/.
• Keep the active todos/ and traces/ entry files concise. Once a stage is complete and validated, move its detailed history into public/<topic>/archive/ and leave only the current recovery point, active facts, active risks, immediate next step, and archive pointers in the default boot path.
• When a topic is complete, move the whole topic directory into public/archive/<topic>/ and remove it from the shared startup index.

Content Rules

• Never write secrets, tokens, credentials, private keys, hostnames, IP addresses, proprietary URLs, or other sensitive data.
• Never write absolute file-system paths, home-directory paths, or machine usernames.
• Use repository-relative paths, branch names, PR numbers, recovery-point IDs, and stable document identifiers instead.
• Keep committed public/** content concise, handoff-safe, and understandable without machine-local context.

Naming

• Topic directories should be named by capability or work direction, for example:
  • public/ai-plan-governance/
  • public/cqrs-rewrite/
• Worktree-private files should live under a folder named for the current branch or worktree, for example:
  • private/feat-cqrs-optimization/
  • private/gframework-cqrs/