.gitignore 🔗
@@ -5,3 +5,5 @@
.aider*
config.toml
lunatask-mcp-server
+_plans/*
+!.gitkeep
docs: split AGENTS.md into modular files
Amolith and Crush created
Split monolithic AGENTS.md into modular documentation:
- Architecture & Design, Build & Development, Code Style
Guidelines, and Configuration Guide
- Added vibe-flow workflow for managing specs and plans
- Created _plans/ directory for implementation artifacts
Co-Authored-By: Crush <crush@charm.land>Change summary
.gitignore | 2
AGENTS.md | 167 --------
_docs/Architecture & Design.md | 53 ++
_docs/Build & Development.md | 50 ++
_docs/Code Style Guidelines.md | 65 +++
_docs/Configuration Guide.md | 49 ++
_docs/vibe-flow/How to Write a Technical Specification.md | 55 ++
_docs/vibe-flow/How to Write an Implementation Plan.md | 70 +++
_docs/vibe-flow/Vibe Flow Guide.md | 45 ++
_plans/.gitkeep | 0
crush.json.license | 3
11 files changed, 410 insertions(+), 149 deletions(-)
Detailed changes
AGENTS.md 🔗
@@ -1,158 +1,27 @@
-# AGENTS.md
+<!--
+SPDX-FileCopyrightText: Amolith <amolith@secluded.site>
-This file provides guidance to AI coding agents when working with code in this repository.
+SPDX-License-Identifier: CC0-1.0
+-->
-## Build Commands
+# lunatask-mcp-server Development Documentation
-All commands use `just` task runner:
+## Important Instructions
-- **Development workflow**: `just` (runs fmt, lint, staticcheck, test, vuln, reuse)
-- **Format code**: `just fmt` (uses gofumpt)
-- **Lint**: `just lint` (uses golangci-lint)
-- **Static analysis**: `just staticcheck` (uses staticcheck)
-- **Test**: `just test` (runs all tests with verbose output)
-- **Single test**: `go test -v ./path/to/package -run TestName`
-- **Vulnerability check**: `just vuln` (uses govulncheck)
-- **License compliance**: `just reuse` (REUSE specification)
-- **Build**: `just build` (outputs to `./lunatask-mcp-server`, supports GOOS/GOARCH env vars)
-- **Run**: `just run` (builds and runs with version injection)
-- **Compress binary**: `just pack` (requires upx, run after build)
-- **Clean**: `just clean` (removes binary) or `just clean-all` (removes binary and config)
+- For each task the user asks, you MUST select the relevant documentation files and read them ENTIRELY.
+- Always ignore the `_plans` directory when you search for anything in the codebase.
-Version is injected at build time via git describe, so always use `just build` or `just run` rather than plain `go build`.
+## Documentation Files
-## Licensing
+Most frequently consulted procedures:
-This project is REUSE compliant. All files must have SPDX headers:
+- `_docs/Code Style Guidelines.md` - ALWAYS READ BEFORE CODING
+- `_docs/Build & Development.md` - Commands for building, testing, and development workflow
+- `_docs/Architecture & Design.md` - Three-layer architecture and design patterns
+- `_docs/Configuration Guide.md` - Complete config.toml structure and setup
-- **Code files** (`.go`): `SPDX-License-Identifier: AGPL-3.0-or-later`
-- **Documentation** (`.md`, `.toml`): `SPDX-License-Identifier: CC0-1.0`
-- **Copyright**: `SPDX-FileCopyrightText: Amolith <amolith@secluded.site>`
+Vibe Flow:
-Always include both lines in new files.
-
-## Architecture Overview
-
-This is an MCP (Model Context Protocol) server that exposes Lunatask API functionality to LLMs. The codebase uses a clean three-layer architecture:
-
-### Layer 1: Main Entry Point (`cmd/lunatask-mcp-server.go`)
-
-- Loads TOML configuration from `config.toml` (or custom path via `-c/--config`)
-- Creates and configures the MCP SSE server (Server-Sent Events transport)
-- Implements Provider interfaces (`AreaProvider`, `GoalProvider`, `HabitProvider`) that wrap config structs
-- Registers all MCP tools with their handlers
-- Validates configuration on startup (areas/goals must have names and IDs, timezone must be valid)
-
-### Layer 2: Tools Package (`tools/`)
-
-- Bridges MCP tool calls to Lunatask API client
-- Handles MCP request/response formatting
-- Performs pre-validation and argument transformation (e.g., string priorities → integers)
-- Consumes Provider interfaces to access configuration without tight coupling
-- Contains handlers for: timestamp parsing, area/goal listing, task CRUD, habit tracking
-
-### Layer 3: Lunatask Package (`lunatask/`)
-
-- Low-level HTTP client for Lunatask REST API (`https://api.lunatask.app/v1`)
-- Defines request/response types with JSON tags
-- Uses `go-playground/validator` for request validation
-- Contains API methods for tasks (`CreateTask`, `UpdateTask`, `DeleteTask`) and habits (`TrackHabitActivity`)
-
-### Key Design Patterns
-
-**Provider Interfaces**: The tools package defines `AreaProvider`, `GoalProvider`, and `HabitProvider` interfaces. The main package's config structs implement these, allowing tools to access config data without importing main or knowing config structure details.
-
-**String-to-Integer Mapping**: MCP tools accept human-readable strings that get translated to API integers:
-- Priority: `"lowest"`=-2, `"low"`=-1, `"neutral"`=0, `"high"`=1, `"highest"`=2
-- Eisenhower matrix: `"uncategorised"`=0, `"both urgent and important"`=1, `"urgent, but not important"`=2, `"important, but not urgent"`=3, `"neither urgent nor important"`=4
-
-**Natural Language Date Parsing**: Uses `github.com/ijt/go-anytime` with timezone support. The `get_timestamp` tool parses expressions like "tomorrow at 3pm" into RFC3339 timestamps. Timezone is configured in `config.toml` using IANA/Olson format (e.g., `America/New_York`).
-
-## Configuration System
-
-On first run, the server generates `config.toml` with placeholder values and exits. Users must:
-
-1. Add their Lunatask API access token
-2. Configure areas with real IDs from Lunatask (areas can have nested goals)
-3. Configure habits with real IDs
-4. Set timezone in IANA format (e.g., `America/New_York`, not `EST`)
-5. Optionally customize server host/port (defaults to `localhost:8080`)
-
-The config uses TOML (not JSON) per project philosophy. Example structure:
-
-```toml
-access_token = "your-token"
-timezone = "America/New_York"
-
-[server]
-host = "localhost"
-port = 8080
-
-[[area]]
-name = "Work"
-id = "uuid-here"
-
- [[area.goal]]
- name = "Q1 Project"
- id = "uuid-here"
-
-[[habit]]
-name = "Exercise"
-id = "uuid-here"
-```
-
-## Critical Implementation Details
-
-### Goal Validation in Task Operations
-
-When creating or updating tasks with a `goal_id`, the tools package validates that the goal belongs to the specified area. This prevents associating tasks with goals from different areas, which Lunatask may reject or handle incorrectly.
-
-### Update vs Create Semantics
-
-`UpdateTask` reuses `CreateTaskRequest` type but has different semantics:
-- Only provided fields are updated (partial updates)
-- Empty strings for text fields (name, note, scheduled_on) clear existing values
-- Empty strings for enum fields (status, motivation) also clear values
-- The tools handler only sends fields present in MCP request arguments
-
-### Empty Package Files
-
-`lunatask/notes.go`, `lunatask/people.go`, and `lunatask/timeline.go` exist but are empty. These are placeholders for future Lunatask API features. Don't remove them without checking if they're imported elsewhere.
-
-### MCP Tool Workflow Dependencies
-
-Several tools must be called in specific order:
-1. `list_areas_and_goals` → provides IDs for `create_task`/`update_task`
-2. `get_timestamp` → provides formatted timestamps for task scheduling and habit tracking
-3. `list_habits_and_activities` → provides IDs for `track_habit_activity`
-
-The MCP tool descriptions document these workflows, and the LLM system prompts (in README.md) reinforce the pattern.
-
-### Validation Happens at Two Levels
-
-1. **Tools layer**: Type checking, area/goal relationship validation, string-to-int translation
-2. **Lunatask layer**: go-playground/validator tags enforce API constraints (UUID format, string lengths, numeric ranges, enum values)
-
-This prevents invalid requests from reaching the API and provides better error messages.
-
-### Version Injection
-
-The `version` variable in main is set via ldflags during build: `-ldflags "-X main.version=..."`. The justfile extracts version from `git describe --long`. Don't hardcode version strings; if version is empty, it displays a helpful message about using `just build`.
-
-## Testing Considerations
-
-- Tests should use `go test -v ./...` to run all packages
-- Mock the HTTP client in lunatask package tests (set `Client.HTTPClient` to custom `*http.Client`)
-- Mock Provider interfaces in tools package tests
-- Timezone-dependent tests should explicitly set timezone in config
-- Natural language date parsing is non-deterministic (relative to "now"), so test with absolute dates or mock time
-
-## Related Documentation
-
-The README.md contains extensive documentation about:
-- MCP tool descriptions and parameters (authoritative reference for tool behavior)
-- Example LLM system prompts showing real-world usage patterns
-- User-specific workflow rules (area workflows, estimate requirements, status defaults)
-- Contribution workflow using pr.pico.sh (SSH-based patches, no GitHub account needed)
-
-When modifying tools, ensure MCP descriptions in `cmd/lunatask-mcp-server.go` stay synchronized with actual behavior.
+- `_docs/vibe-flow/How to Write a Technical Specification.md` - For writing a **spec**
+- `_docs/vibe-flow/How to Write an Implementation Plan.md` - For writing a **plan**
+- `_docs/vibe-flow/Vibe Flow Guide.md` - Where plans, specifications, and implementation summaries are kept
_docs/Architecture & Design.md 🔗
@@ -0,0 +1,53 @@
+<!--
+SPDX-FileCopyrightText: Amolith <amolith@secluded.site>
+
+SPDX-License-Identifier: CC0-1.0
+-->
+
+# Architecture & Design
+
+This document provides a comprehensive guide to the codebase architecture and core design decisions. The project uses a clean three-layer architecture that separates concerns between MCP server handling, business logic, and API client operations.
+
+## Architecture Overview
+
+This is an MCP (Model Context Protocol) server that exposes Lunatask API functionality to LLMs. The codebase uses a clean three-layer architecture:
+
+### Layer 1: Main Entry Point (`cmd/lunatask-mcp-server.go`)
+
+- Loads TOML configuration from `config.toml` (or custom path via `-c/--config`)
+- Creates and configures the MCP SSE server (Server-Sent Events transport)
+- Implements Provider interfaces (`AreaProvider`, `GoalProvider`, `HabitProvider`) that wrap config structs
+- Registers all MCP tools with their handlers
+- Validates configuration on startup (areas/goals must have names and IDs, timezone must be valid)
+
+### Layer 2: Tools Package (`tools/`)
+
+- Bridges MCP tool calls to Lunatask API client
+- Handles MCP request/response formatting
+- Performs pre-validation and argument transformation (e.g., string priorities → integers)
+- Consumes Provider interfaces to access configuration without tight coupling
+- Contains handlers for: timestamp parsing, area/goal listing, task CRUD, habit tracking
+
+### Layer 3: Lunatask Package (`lunatask/`)
+
+- Low-level HTTP client for Lunatask REST API (`https://api.lunatask.app/v1`)
+- Defines request/response types with JSON tags
+- Uses `go-playground/validator` for request validation
+- Contains API methods for tasks (`CreateTask`, `UpdateTask`, `DeleteTask`) and habits (`TrackHabitActivity`)
+
+## Key Design Patterns
+
+**Provider Interfaces**: The tools package defines `AreaProvider`, `GoalProvider`, and `HabitProvider` interfaces. The main package's config structs implement these, allowing tools to access config data without importing main or knowing config structure details.
+
+**String-to-Integer Mapping**: MCP tools accept human-readable strings that get translated to API integers:
+- Priority: `"lowest"`=-2, `"low"`=-1, `"neutral"`=0, `"high"`=1, `"highest"`=2
+- Eisenhower matrix: `"uncategorised"`=0, `"both urgent and important"`=1, `"urgent, but not important"`=2, `"important, but not urgent"`=3, `"neither urgent nor important"`=4
+
+**Natural Language Date Parsing**: Uses `github.com/ijt/go-anytime` with timezone support. The `get_timestamp` tool parses expressions like "tomorrow at 3pm" into RFC3339 timestamps. Timezone is configured in `config.toml` using IANA/Olson format (e.g., `America/New_York`).
+
+## Validation Happens at Two Levels
+
+1. **Tools layer**: Type checking, area/goal relationship validation, string-to-int translation
+2. **Lunatask layer**: go-playground/validator tags enforce API constraints (UUID format, string lengths, numeric ranges, enum values)
+
+This prevents invalid requests from reaching the API and provides better error messages.
_docs/Build & Development.md 🔗
@@ -0,0 +1,50 @@
+<!--
+SPDX-FileCopyrightText: Amolith <amolith@secluded.site>
+
+SPDX-License-Identifier: CC0-1.0
+-->
+
+# Build & Development
+
+This document serves as the reference for all development workflow commands and testing practices. All build operations must use `just` commands rather than plain `go build` to ensure proper version injection.
+
+## Build Commands
+
+All commands use `just` task runner:
+
+- **Development workflow**: `just` (runs fmt, lint, staticcheck, test, vuln, reuse)
+- **Format code**: `just fmt` (uses gofumpt)
+- **Lint**: `just lint` (uses golangci-lint)
+- **Static analysis**: `just staticcheck` (uses staticcheck)
+- **Test**: `just test` (runs all tests with verbose output)
+- **Single test**: `go test -v ./path/to/package -run TestName`
+- **Vulnerability check**: `just vuln` (uses govulncheck)
+- **License compliance**: `just reuse` (REUSE specification)
+- **Build**: `just build` (outputs to `./lunatask-mcp-server`, supports GOOS/GOARCH env vars)
+- **Run**: `just run` (builds and runs with version injection)
+- **Compress binary**: `just pack` (requires upx, run after build)
+- **Clean**: `just clean` (removes binary) or `just clean-all` (removes binary and config)
+
+Version is injected at build time via git describe, so always use `just build` or `just run` rather than plain `go build`.
+
+## Version Injection
+
+The `version` variable in main is set via ldflags during build: `-ldflags "-X main.version=..."`. The justfile extracts version from `git describe --long`. Don't hardcode version strings; if version is empty, it displays a helpful message about using `just build`.
+
+## Testing Considerations
+
+- Tests should use `go test -v ./...` to run all packages
+- Mock the HTTP client in lunatask package tests (set `Client.HTTPClient` to custom `*http.Client`)
+- Mock Provider interfaces in tools package tests
+- Timezone-dependent tests should explicitly set timezone in config
+- Natural language date parsing is non-deterministic (relative to "now"), so test with absolute dates or mock time
+
+## Related Documentation
+
+The README.md contains extensive documentation about:
+- MCP tool descriptions and parameters (authoritative reference for tool behavior)
+- Example LLM system prompts showing real-world usage patterns
+- User-specific workflow rules (area workflows, estimate requirements, status defaults)
+- Contribution workflow using pr.pico.sh (SSH-based patches, no GitHub account needed)
+
+When modifying tools, ensure MCP descriptions in `cmd/lunatask-mcp-server.go` stay synchronized with actual behavior.
_docs/Code Style Guidelines.md 🔗
@@ -0,0 +1,65 @@
+<!--
+SPDX-FileCopyrightText: Amolith <amolith@secluded.site>
+
+SPDX-License-Identifier: CC0-1.0
+-->
+
+# Code Style Guidelines
+
+## Licensing & File Headers
+
+All files require SPDX headers:
+
+- **Go files**: `AGPL-3.0-or-later`
+- **Documentation/config** (`.md`, `.toml`): `CC0-1.0`
+- **Copyright**: `Amolith <amolith@secluded.site>`
+
+Include both lines as comments at the top of every new file. Annotate with `reuse annotate -c "Amolith <amolith@secluded.site>" -l '<license_id>' --exclude-year 'path/to/file'`.
+
+## Go Code Style
+
+- Use `gofumpt` for formatting (`just fmt`)
+- Use `golangci-lint` for linting (`just lint`)
+- Use `staticcheck` for static analysis (`just staticcheck`)
+- Export types/functions with godoc comments starting with the name
+- Use provider interfaces to decouple packages (see `AreaProvider`, `GoalProvider`, `HabitProvider`)
+- Keep validation at two levels: tools layer (relationships, type checking) and lunatask layer (go-playground/validator tags)
+
+## Configuration
+
+- Use TOML for configuration files, not JSON (per project philosophy)
+- Use IANA/Olson timezone format (`America/New_York`, not `EST`)
+- See `Configuration Guide.md` for complete config.toml structure and validation
+- See `Build & Development.md` and `Architecture & Design.md` for additional implementation context
+
+## Implementation Rules
+
+### Goal Validation in Task Operations
+
+When creating or updating tasks with a `goal_id`, the tools package validates that the goal belongs to the specified area. This prevents associating tasks with goals from different areas, which Lunatask may reject or handle incorrectly.
+
+### Update vs Create Semantics
+
+`UpdateTask` reuses `CreateTaskRequest` type but has different semantics:
+- Only provided fields are updated (partial updates)
+- Empty strings for text fields (name, note, scheduled_on) clear existing values
+- Empty strings for enum fields (status, motivation) also clear values
+- The tools handler only sends fields present in MCP request arguments
+
+### Empty Package Files
+
+`lunatask/notes.go`, `lunatask/people.go`, and `lunatask/timeline.go` exist but are empty. These are placeholders for future Lunatask API features. Don't remove them without checking if they're imported elsewhere.
+
+### MCP Tool Workflow Dependencies
+
+Several tools must be called in specific order:
+1. `list_areas_and_goals` → provides IDs for `create_task`/`update_task`
+2. `get_timestamp` → provides formatted timestamps for task scheduling and habit tracking
+3. `list_habits_and_activities` → provides IDs for `track_habit_activity`
+
+The MCP tool descriptions document these workflows, and the LLM system prompts (in README.md) reinforce the pattern.
+
+## Build & Version
+
+- Always use `just build` or `just run`, never plain `go build` (version injection via ldflags)
+- Version is extracted from `git describe --long`
_docs/Configuration Guide.md 🔗
@@ -0,0 +1,49 @@
+<!--
+SPDX-FileCopyrightText: Amolith <amolith@secluded.site>
+
+SPDX-License-Identifier: CC0-1.0
+-->
+
+# Configuration Guide
+
+This document describes the configuration system for the Lunatask MCP server. The server uses TOML for configuration files rather than JSON, following the project philosophy that configuration should be human-readable and editable. Configuration is validated on startup to ensure all required fields are present and correctly formatted.
+
+## First-Run Behavior
+
+On first run, the server generates `config.toml` with placeholder values and exits. Users must:
+
+1. Add their Lunatask API access token
+2. Configure areas with real IDs from Lunatask (areas can have nested goals)
+3. Configure habits with real IDs
+4. Set timezone in IANA format (e.g., `America/New_York`, not `EST`)
+5. Optionally customize server host/port (defaults to `localhost:8080`)
+
+## Configuration Structure
+
+The config uses TOML (not JSON) per project philosophy. Example structure:
+
+```toml
+access_token = "your-token"
+timezone = "America/New_York"
+
+[server]
+host = "localhost"
+port = 8080
+
+[[area]]
+name = "Work"
+id = "uuid-here"
+
+ [[area.goal]]
+ name = "Q1 Project"
+ id = "uuid-here"
+
+[[habit]]
+name = "Exercise"
+id = "uuid-here"
+```
+
+## Additional Notes
+
+- For valid timezone values, see the IANA timezone database: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+- Configuration is validated on startup using go-playground/validator tags in the lunatask package
_docs/vibe-flow/How to Write a Technical Specification.md 🔗
@@ -0,0 +1,55 @@
+<!--
+SPDX-FileCopyrightText: Amolith <amolith@secluded.site>
+
+SPDX-License-Identifier: CC0-1.0
+-->
+
+# How to Write a Technical Specification
+
+## Pre-requisites
+
+Before you start, read the `Vibe Flow Guide.md` entirely.
+
+You need:
+
+- the TASK_DIR - if you don't have it, ask the user for a **ticket ID**
+- the current CYCLE_LETTER and the next FILE_NUMBER - deduce them by yourself - by default, start with a new cycle (bump the CYCLE_LETTER, reset the FILE_NUMBER to 1)
+
+## Phases
+
+When the user asks you for a SPEC (technical specification), you MUST follow this process:
+
+1. **Investigation Phase**: Research the codebase to understand the current implementation and identify the problem
+2. **Discussion Phase**: Collaborate with the user to explore the problem space and potential solutions BEFORE writing the specification file
+3. **Specification Phase**: Only after user approval, write the final specification file
+
+The discussion phase is MANDATORY. Remember that you are a newcomer to this project while the user has extensive experience with the codebase and will be happy to help guide you.
+
+## Discussion Format
+
+Engage in a thorough collaborative discussion covering:
+
+- **Problem exploration**: Present your understanding of the problem and ask clarifying questions
+- **Current implementation analysis**: Share what you discovered and ask for confirmation or corrections
+- **Multiple solution approaches**: Present several viable alternatives when they exist, explaining trade-offs
+- **Sub-subject identification**: Break down the problem into all relevant sub-components and ensure each is addressed
+- **Design decisions**: Ask for user input on key architectural choices
+- **Edge cases and implications**: Explore potential issues and broader system impacts
+
+You should ask questions freely to ensure you fully understand:
+
+- The problem context and requirements
+- Existing patterns and conventions in the codebase
+- User preferences for implementation approaches
+- Any constraints or considerations you might have missed
+
+## Specification File Guidelines
+
+After the user approves your proposal, write the specification in a markdown file in TASK_DIR. Compose the filename with the current CYCLE_LETTER and the next FILE_NUMBER, e.g. `A1-spec.md`. Do not overwrite an existing file.
+
+- Usually a specification is around 40~60 lines
+- **Do not add backward compatibility** unless explicitly requested. Prefer clean code. Unused code must be removed.
+- A specification is not always immediately executed, and you have to assume that the code can change before it is executed. You can mention a function by name, but NEVER mention specific line numbers as they will become obsolete
+- Do not include any detailed code in the specification. Instead, refer to the relevant source files by their paths or function names
+- Assume that the specification will be read by developers familiar with the codebase
+- Do not include sections like "Benefits", "Code Style Compliance" or anything that adds no new information. Focus on the problem and the solution
_docs/vibe-flow/How to Write an Implementation Plan.md 🔗
@@ -0,0 +1,70 @@
+<!--
+SPDX-FileCopyrightText: Amolith <amolith@secluded.site>
+
+SPDX-License-Identifier: CC0-1.0
+-->
+
+# How to Write an Implementation Plan
+
+## Pre-requisites
+
+Before you start, read the `Vibe Flow Guide.md` entirely.
+
+You need:
+
+- the TASK_DIR - if you don't have it, ask the user for a **ticket ID**
+- the current CYCLE_LETTER and the bumped FILE_NUMBER - deduce them by yourself
+- a SPEC (technical specification) - if you don't have it, ask the user for it
+
+## Creating an Implementation Plan
+
+This is a procedure for a planning-only task. Help the user design an implementation plan for improving this project.
+
+Use the SPEC text as a starting point, but do not trust it. Investigate the codebase yourself, find the relevant source code, think carefully, take the time to understand how it currently works and what has to be done.
+
+Remember that you are a newcomer to this project while the user has extensive experience with the codebase and will be happy to help guide you. If you have any doubt, or if you discover that an important design choice still needs to be made, STOP and ask.
+
+### Guidelines
+
+- The implementation plan must be a **self-explanatory prompt** for a coding agent, so help it by explaining what you discovered.
+- Give some context: explain how it works currently, and how it will work after the task is done.
+- In a "Prerequisites" section, select the **relevant documentation** from the `_docs/` directory. Do not repeat any documentation. Instead, mention the documentation that needs to be read. Always include `Code Style Guidelines.md` in the list.
+- Mention a way to find **important source files**: by giving file paths, or by providing a function name to search for, for example. If needed, line numbers can be mentioned in the plan.
+- Include a list of **numbered steps** and all useful information from the SPEC:
+ - If the SPEC is already a good plan, you can use it as-is. You can also extract and reuse parts of it.
+ - Do not add **backwards compatibility** unless explicitly requested. Prefer clean code. Unused code must be removed.
+ - About **tests**: Investigate first in the codebase if there are tests already in place for the kind of tests you consider. Do not mention to write tests unless you are sure they will be well-integrated in the project.
+
+### Add a Final Step to the Plan
+
+In your plan there is a list of steps. Add a new step named "Write a Handover Document" with this content:
+
+<content_to_add>
+Write a **handover document**. This document must contain the list of all files you updated. Also, summarize the changes made in a very concise way. Add only relevant information that will help your teammates understand what's new. Do not mention obvious information. It's not a course or a tutorial, if there is nothing to explain, then do not explain. Write this handover document in a new `{TASK_DIR}/{TASK_FILE_PREFIX}-summary.md` markdown file. Avoid overwriting an existing file. Ignore lint errors (formatting issues) in this file.
+</content_to_add>
+
+Note:
+
+- This is a regular step, it should be numbered like the other steps.
+- Replace "{TASK_DIR}" with the actual TASK_DIR, e.g. `_plans/123/`
+- Replace "{TASK_FILE_PREFIX}" with the current CYCLE_LETTER and the FILE_NUMBER of the plan plus one, e.g. `A3`
+
+### Last Paragraph
+
+Add the following content to the very end of the implementation plan:
+
+<content_to_add>
+---
+
+Do not trust this implementation plan blindly. Be sure you understand the codebase and the plan by yourself before applying it.
+</content_to_add>
+
+## Save the Implementation Plan
+
+Write your plan in a markdown file in TASK_DIR. Compose the filename with the current CYCLE_LETTER and the FILE_NUMBER incremented from the last one in the same cycle, e.g. `A2-plan.md`. Do not overwrite an existing file.
+
+_Important Note: There will be lint errors in the markdown file you write. Ignore them. NEVER FIX LINT ERRORS (FORMATTING ISSUES) IN THE PLAN._
+
+## Improve the PLAN
+
+When you think the plan is complete, read it again with a critical eye, edit it to improve it. Repeat until you think it's solid.
_docs/vibe-flow/Vibe Flow Guide.md 🔗
@@ -0,0 +1,45 @@
+<!--
+SPDX-FileCopyrightText: Amolith <amolith@secluded.site>
+
+SPDX-License-Identifier: CC0-1.0
+-->
+
+# Vibe Flow Guide
+
+## TASK_DIR Location
+
+**TASK_DIR** is the directory where work files related to a task are stored. Usually, we use **TASK_DIR** = `_plans/{TICKET_ID}/` (a sub-directory of the `_plans` folder). If no ticket ID is known, ask the user for it.
+
+- Create TASK_DIR if it doesn't exist
+- Or, list existing files
+
+## File Naming Convention
+
+Format: `{CYCLE_LETTER}{FILE_NUMBER}-{FILE_TYPE}.md`
+
+**Common file types:**
+
+- `spec` - technical specification
+- `plan` - implementation plan
+- `summary` - implementation summary document
+- `commit` - suggested commit message and changelog entry
+
+**Example structure:**
+
+```text
+_plans/
+├── 123/
+│ ├── A1-spec.md
+│ ├── A2-plan.md
+│ ├── A3-summary.md
+│ └── B1-spec.md
+```
+
+## Notes
+
+- **TICKET_ID** is a unique identifier for the task, often an issue or ticket number.
+- Cycles are identified by a **CYCLE_LETTER** (A, B, C...). The user decides when to start a new one.
+- In a cycle, determine the next **FILE_NUMBER** from existing file names. Every new file must have a bumped file number.
+- Do not bother the user with CYCLE_LETTER or FILE_NUMBER. They are for internal organization. It's up to you to list the files and determine the last CYCLE_LETTER and FILE_NUMBER. Start CYCLE_LETTER with `A` if there is no existing cycle, and FILE_NUMBER with `1`. So you just need to ask for a **ticket ID** if you don't have one.
+- When the user requests a new cycle: bump CYCLE_LETTER and reset FILE_NUMBER.
+- There is no strict sequence of file types in the workflow. Available file types are also flexible; if you need a new one, just create it.
_plans/.gitkeep 🔗
crush.json.license 🔗
@@ -0,0 +1,3 @@
+SPDX-FileCopyrightText: Amolith <amolith@secluded.site>
+
+SPDX-License-Identifier: CC0-1.0