nflectures2026

Imported from X6TXY/nflectures2026 (AGENTS.md). Install upstream with npx skills add X6TXY/nflectures2026. Copyright stays with the author.

Documentation Convention (MANDATORY)

This convention is COMPULSORY. You MUST follow it for every plan, feature, or system you document. No exceptions.

All documentation lives in docs/ and follows a structured planning workflow.

Directory Structure

docs/
├── systems/                              # Living docs for shipped systems
│   ├── <system-name>/
│   │   ├── README.md                     # Compiled from plan.md + all task files
│   │   └── diagram.excalidraw           # Architecture / data flow diagram
│   └── ...
├── plans/                                # Upcoming features and designs
│   ├── YYYY-MM-DD-<feature-name>/
│   │   ├── plan.md                       # Overall plan: overview, goals, architecture, scope
│   │   ├── diagram.excalidraw           # Architecture diagram for the feature
│   │   ├── blockers.excalidraw          # Dependency/blocker diagram between tasks
│   │   ├── 01-<task-name>.md            # Task 1: detailed implementation spec
│   │   ├── 02-<task-name>.md            # Task 2: detailed implementation spec
│   │   ├── 03-<task-name>.md            # Task 3: detailed implementation spec
│   │   └── ...                           # As many tasks as needed
│   └── ...
├── TRACKER.yaml                          # Tracks plans AND individual tasks

Planning Workflow (MANDATORY — follow every step)

Step 1: Create the Plan Folder

Create docs/plans/YYYY-MM-DD-<feature-name>/ with:

1. plan.md — The overall plan document containing:

   • Feature overview and goals
   • Architecture decisions and rationale
   • Scope and constraints
   • List of tasks with brief descriptions

2. diagram.excalidraw — Architecture diagram showing how the feature works:

   • System components involved
   • Data flows
   • External dependencies
   • Create via Excalidraw MCP tools, then write the .excalidraw JSON file

3. Individual task files (01-<task-name>.md, 02-<task-name>.md, etc.):

   • Each file is a self-contained implementation spec for one step
   • Numbered to indicate execution order
   • Contains: what to build, acceptance criteria, files to modify, dependencies
   • These are followed step-by-step during implementation

4. blockers.excalidraw — Blocker/dependency diagram showing:

   • Which tasks block which other tasks
   • The execution order and parallelization opportunities
   • Critical path through the plan
   • Create via Excalidraw MCP tools

Step 2: Update TRACKER.yaml

Add the plan AND all individual tasks to docs/TRACKER.yaml:

plans:
  - name: feature-name
    path: plans/YYYY-MM-DD-feature-name/
    status: planned # planned → in-progress → shipped
    created: YYYY-MM-DD
    started:
    shipped:
    tasks:
      - name: task-1-name
        file: 01-task-name.md
        status: pending # pending → in-progress → done
      - name: task-2-name
        file: 02-task-name.md
        status: pending

Step 3: Implementation (follow tasks in order, keep everything in sync)

Work through task files in numbered order (unless blockers allow parallelization). You MUST keep TRACKER.yaml in sync at every state change. This is not just about creating tickets — you must actively maintain them throughout the plan lifecycle.

When starting a task:

• Update docs/TRACKER.yaml task status to in-progress
• If this is the first task being started, also update the parent ticket and plan status to in-progress

When completing a task:

• Update docs/TRACKER.yaml task status to done
• Check if any previously blocked tasks are now unblocked and mention this

When a task is blocked or has issues:

• Do NOT silently skip — communicate the issue

At the start of every implementation session:

• Check docs/TRACKER.yaml to understand current progress
• Resume from where the last session left off

Step 4: Shipping (move to systems)

When ALL tasks are complete:

1. Compile README.md — Create docs/systems/<system-name>/README.md by combining:

   • The overview and architecture from plan.md
   • Key details from each individual task file
   • Final architecture decisions and operational notes

2. Copy the architecture diagram — Move diagram.excalidraw to docs/systems/<system-name>/

3. Move the folder — Move from plans/ to systems/

4. Update TRACKER.yaml — Set plan status to shipped with shipped: date

Rules (ALL mandatory — do not skip any)

• Every plan folder MUST have: plan.md, diagram.excalidraw, blockers.excalidraw, and at least one task file
• Diagrams use Excalidraw — create via the Excalidraw MCP tool, then write the .excalidraw JSON file
• When creating diagrams: use create_element for rectangles, text, arrows etc., then query_elements to get all elements, then write to .excalidraw file format
• The .excalidraw file is viewable in VS Code with the Excalidraw extension, or at excalidraw.com
• NEVER create a plan without an architecture diagram AND a blockers diagram
• ALWAYS update docs/TRACKER.yaml when creating, starting, completing tasks, or shipping a plan
• At the start of each session, check TRACKER.yaml to understand current plan progress before doing work

Plan Tracker (MANDATORY)

docs/TRACKER.yaml is the source of truth for plan progress. You MUST update whenever you:

Plan statuses: planned → in-progress → shipped Task statuses: pending → in-progress → done

Failure to keep TRACKER.yaml in sync is a violation of this convention.

Diagram Maintenance

When making architectural changes, update diagram.excalidraw in this directory. This includes:

• Adding/removing dependencies in di-config
• Modifying the third-party dependencies

Also update docs/systems/api/diagram.excalidraw to keep the system documentation in sync.