@prmichaelsen/firebase-admin-sdk-v8 2.8.0 → 2.9.0

package/AGENT.md

@@ -1,7 +1,7 @@
 # Agent Context Protocol (ACP)
 
 **Also Known As**: The Agent Directory Pattern
-**Version**: 3.13.0
+**Version**: 5.22.0
 **Created**: 2026-02-11
 **Status**: Production Pattern
 
@@ -17,9 +17,17 @@
 6. [How to Use the Agent Pattern](#how-to-use-the-agent-pattern)
 7. [Pattern Significance & Impact](#pattern-significance--impact)
 8. [Problems This Pattern Solves](#problems-this-pattern-solves)
-9. [Instructions for Future Agents](#instructions-for-future-agents)
-10. [Real-World Example: remember-mcp](#real-world-example-remember-mcp)
+9. [Key File Index](#key-file-index)
+10. [Instructions for Future Agents](#instructions-for-future-agents)
 11. [Best Practices](#best-practices)
+    - [Critical Rules](#critical-rules)
+    - [Workflow Best Practices](#workflow-best-practices)
+    - [Documentation Best Practices](#documentation-best-practices)
+    - [Organization Best Practices](#organization-best-practices)
+    - [Progress Tracking Best Practices](#progress-tracking-best-practices)
+    - [Quality Best Practices](#quality-best-practices)
+12. [What NOT to Do](#what-not-to-do)
+13. [Keeping ACP Updated](#keeping-acp-updated)
 
 ---
 
@@ -110,9 +118,22 @@ project-root/
 │   │
 │   ├── tasks/                      # Granular tasks
 │   │   ├── .gitkeep
-│   │   ├── task-1-{name}.md
-│   │   ├── task-2-{name}.md
-│   │   └── ...
+│   │   ├── milestone-{N}-{title}/  # Tasks grouped by milestone (standard)
+│   │   │   ├── task-{M}-{name}.md
+│   │   │   └── ...
+│   │   ├── unassigned/             # Tasks without milestone
+│   │   │   └── task-{M}-{name}.md
+│   │   └── task-{N}-{name}.md      # Legacy flat structure (older tasks)
+│   │
+│   ├── files/                      # Template source files (in packages)
+│   │   ├── config/                 # Config templates
+│   │   └── src/                    # Source code templates
+│   │
+│   ├── index/                      # Key file index
+│   │   ├── .gitkeep
+│   │   ├── local.main.yaml         # Project's own key files
+│   │   ├── local.main.template.yaml# Template with schema docs
+│   │   └── {pkg}.main.yaml         # Package-shipped indices
 │   │
 │   └── progress.yaml               # Progress tracking
 │
@@ -279,6 +300,7 @@ project:
 milestones:
   - id: M1
     name: Milestone Name
+    file: agent/milestones/milestone-1-name.md
     status: not_started | in_progress | completed
     progress: 0-100%
     started: YYYY-MM-DD
@@ -294,13 +316,19 @@ tasks:
     - id: task-1
       name: Task Name
       status: not_started | in_progress | completed
-      file: agent/tasks/task-1-name.md
+      started: ISO-8601 | null
+      file: agent/tasks/milestone-{N}-{title}/task-{M}-name.md
       estimated_hours: N
-      actual_hours: null
-      completed_date: YYYY-MM-DD | null
+      actual_hours: null              # auto-computed
+      completed_date: ISO-8601 | null
       notes: |
         Task notes
 
+**Timestamp Rules**:
+- `started` — auto-set to ISO 8601 timestamp when task first transitions to `in_progress`. Never overwritten once set.
+- `completed_date` — auto-set to ISO 8601 timestamp when task transitions to `completed`.
+- `actual_hours` — auto-computed as `(completed_date - started)` in hours, rounded to 1 decimal. Not manually set.
+
 documentation:
   design_documents: N
   milestone_documents: N
@@ -345,10 +373,9 @@ current_blockers:
    touch agent/{design,milestones,patterns,tasks}/.gitkeep
    ```
 
-2. **Write Requirements Document**
-   - Create `agent/design/requirements.md`
-   - Document core requirements, constraints, and goals
-   - Define success criteria
+2. **Create Requirements Document**
+   - Invoke [`@acp.design-create`](agent/commands/acp.design-create.md) and follow directives defined in that file
+   - Specify "requirements" as the design type
 
 3. **Define Milestones**
    - Break project into 5-10 major phases
@@ -356,9 +383,8 @@ current_blockers:
    - Clear deliverables and success criteria
 
 4. **Create Initial Tasks**
+   - Invoke [`@acp.task-create`](agent/commands/acp.task-create.md) and follow directives defined in that file
    - Break first milestone into concrete tasks
-   - Each task should be 1-4 hours of work
-   - Include verification steps
 
 5. **Initialize Progress Tracking**
    - Create `agent/progress.yaml`
@@ -366,9 +392,8 @@ current_blockers:
    - Document initial status
 
 6. **Document Patterns**
-   - Create `agent/patterns/bootstrap.md` with setup instructions
+   - Invoke [`@acp.pattern-create`](agent/commands/acp.pattern-create.md) and follow directives defined in that file
    - Document architectural decisions as patterns
-   - Include code examples
 
 ### For Continuing an Existing Project
 
@@ -402,25 +427,7 @@ current_blockers:
    - Add notes about work completed
    - Document any new patterns or decisions
 
-### For Adding New Features
-
-1. **Create Design Document**
-   - Document in `agent/design/{feature}-design.md`
-   - Include problem, solution, implementation
-   - Get approval before proceeding
-
-2. **Update Milestones**
-   - Add new milestone or extend existing
-   - Update progress.yaml
-
-3. **Create Tasks**
-   - Break feature into tasks
-   - Add to appropriate milestone
-   - Include verification steps
-
-4. **Document Patterns**
-   - If feature introduces new patterns, document them
-   - Update existing patterns if needed
+> **See also**: [Best Practices](#best-practices) for detailed guidance on documentation, organization, and quality standards.
 
 ---
 
@@ -601,41 +608,9 @@ Commands are invoked using the `@` syntax with dot notation:
 
 ### Creating Custom Commands
 
-To create custom commands for your project:
-
-1. **Choose a namespace** (e.g., `deploy`, `test`, `custom`)
-   - ⚠️ The `acp` namespace is reserved for core commands
-   - Use descriptive, single-word namespaces
-
-2. **Copy the command template**:
-   ```bash
-   cp agent/commands/command.template.md agent/commands/{namespace}.{action}.md
-   ```
+Invoke [`@acp.command-create`](agent/commands/acp.command-create.md) and follow directives defined in that file.
 
-3. **Fill in the template sections**:
-   - Purpose and description
-   - Prerequisites
-   - Step-by-step instructions
-   - Verification checklist
-   - Examples and troubleshooting
-
-4. **Invoke your command**: `@{namespace}.{action}`
-
-**Example**: Creating a deployment command:
-```bash
-# Create the command file
-cp agent/commands/command.template.md agent/commands/deploy.production.md
-
-# Edit the file with your deployment steps
-# ...
-
-# Invoke it
-@deploy.production
-```
-
-### Command Template
-
-See [`agent/commands/command.template.md`](agent/commands/command.template.md) for the complete command template with all sections and examples.
+**Note**: The `acp` namespace is reserved for core commands. Use descriptive, single-word namespaces for custom commands (e.g., `local`, `deploy`, `test`, `custom`).
 
 ### Installing Third-Party Commands
 
@@ -720,6 +695,123 @@ When working in any project, you can discover globally installed packages:
 
 ---
 
+## Project Registry System
+
+ACP supports a global project registry at `~/.acp/projects.yaml` that tracks all projects in the `~/.acp/projects/` workspace. This enables project discovery, context switching, and metadata management across your entire ACP workspace.
+
+### Key Features
+
+- **Project Discovery**: List all registered projects with filtering options
+- **Context Switching**: Quickly switch between projects using `@acp.project-set`
+- **Metadata Tracking**: Track project type, status, tags, and relationships
+- **Automatic Registration**: Projects auto-register when created via `@acp.project-create`
+- **Sync Discovery**: Find and register existing projects with `@acp.projects-sync`
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| [`@acp.project-list`](agent/commands/acp.project-list.md) | List all registered projects with optional filtering |
+| [`@acp.project-set`](agent/commands/acp.project-set.md) | Switch to a project (set as current) |
+| [`@acp.project-info`](agent/commands/acp.project-info.md) | Show detailed project information |
+| [`@acp.project-update`](agent/commands/acp.project-update.md) | Update project metadata |
+| [`@acp.project-remove`](agent/commands/acp.project-remove.md) | Remove project from registry |
+| [`@acp.projects-sync`](agent/commands/acp.projects-sync.md) | Discover and register existing projects |
+
+### Registry Structure
+
+The `~/.acp/projects.yaml` file tracks all registered projects:
+
+```yaml
+projects:
+  - name: my-project
+    path: /home/user/.acp/projects/my-project
+    type: library
+    status: in_progress
+    registered: 2026-02-23T10:00:00Z
+    last_accessed: 2026-02-26T15:30:00Z
+    tags:
+      - typescript
+      - npm
+    related_projects: []
+    description: My awesome project
+
+current_project: my-project
+```
+
+### Example Workflow
+
+```bash
+# List all projects
+@acp.project-list
+
+# Switch to a specific project
+@acp.project-set my-project
+
+# View project details
+@acp.project-info
+
+# Update project metadata
+@acp.project-update --tags "typescript,api,rest"
+
+# Discover unregistered projects
+@acp.projects-sync
+
+# Remove a project from registry (keeps files)
+@acp.project-remove old-project
+```
+
+### For Agents: How to Use the Registry
+
+When working in any ACP project, you can:
+
+1. **Check current project**: Read `~/.acp/projects.yaml` and find `current_project`
+2. **List available projects**: Use `@acp.project-list` to see all projects
+3. **Switch context**: Use `@acp.project-set <name>` to change projects
+4. **Get project info**: Use `@acp.project-info` for detailed metadata
+
+**Automatic Tracking**: The `@acp.init` command automatically reads the registry and reports the current project context.
+
+---
+
+## Sessions System
+
+ACP supports global session tracking via `~/.acp/sessions.yaml` for awareness of concurrent agent work across projects. When multiple `claude` terminals run from a single IDE instance, sessions give each agent visibility into what other agents are doing.
+
+This is an advisory-only visibility layer — no locking or coordination. Sessions are registered at `@acp.init` and deregistered at `@acp.report`, with automatic stale cleanup for crashed terminals.
+
+### What sessions.yaml Tracks
+
+Each session entry contains: session ID, project name, description, timestamps (started, last_activity), status (active/idle), current milestone and task, PID (for stale detection), terminal, and optional remote URL.
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| [`@acp.sessions`](agent/commands/acp.sessions.md) | List, clean, deregister, or count sessions |
+| `@acp.sessions list` | Show all active sessions |
+| `@acp.sessions clean` | Remove stale sessions (dead PIDs, timeouts) |
+| `@acp.sessions deregister` | End current session |
+
+### Integration with Other Commands
+
+| Command | Integration |
+|---------|-------------|
+| `@acp.init` | Registers session and displays active siblings |
+| `@acp.status` | Shows session count ("Sessions: N active") |
+| `@acp.report` | Deregisters session on completion |
+
+All integrations are optional — if `acp.sessions.sh` is missing, commands skip the session step silently.
+
+### Session Lifecycle
+
+1. **Register**: `@acp.init` registers a session with project, PID, timestamps
+2. **Heartbeat**: Activity updates via `acp.sessions.sh heartbeat`
+3. **Deregister**: `@acp.report` ends the session, or manual via `@acp.sessions deregister`
+4. **Stale Cleanup**: Dead PIDs removed immediately; inactive >2h removed; inactive >30m marked idle
+
+---
+
 ## Experimental Features
 
 ACP supports marking features as "experimental" to enable safe innovation without affecting stable installations.
@@ -797,6 +889,196 @@ Validation ensures consistency:
 
 ---
 
+## Benchmark Suite
+
+ACP includes an automated E2E benchmark system that compares project outcomes with and without ACP to generate quantitative success metrics.
+
+### Quick Start
+
+```bash
+# Run all benchmarks (ACP vs baseline)
+bash agent/benchmarks/runner/run-benchmark.sh
+
+# Run a specific task
+bash agent/benchmarks/runner/run-benchmark.sh --task complex-auth-system
+
+# Run ACP mode only, 3 runs for statistical averaging
+bash agent/benchmarks/runner/run-benchmark.sh --task medium-rest-api --acp-only --runs 3
+
+# Serve HTML reports
+bash agent/benchmarks/runner/serve-reports.sh
+```
+
+### Benchmark Tasks
+
+| Task | Complexity | Steps | Description |
+|------|-----------|-------|-------------|
+| hello-world | simple | 1 | Basic script creation |
+| simple-cli-tool | medium | 3 | CSV-to-JSON CLI tool |
+| medium-rest-api | medium | 4 | Express CRUD API with refactoring |
+| complex-auth-system | complex | 5 | JWT authentication system |
+| legacy-refactor | complex | 6 | Refactor messy legacy app (seed-based) |
+| order-pipeline | complex | 7 | Order system with event-driven pivot |
+
+### How It Works
+
+1. Each task runs in an isolated temp directory using `claude -p` (non-interactive mode)
+2. Multi-turn conversations use `--resume` for step-by-step execution
+3. ACP mode installs ACP and injects `@acp.plan` / `@acp.proceed` directives
+4. After execution: automated verification checks + LLM evaluator (6-category rubric)
+5. Reports generated in Markdown and HTML (with Chart.js radar charts)
+
+### Key Files
+
+- `agent/benchmarks/runner/run-benchmark.sh` — Main entry point
+- `agent/benchmarks/runner/run-single.sh` — Single task/mode runner
+- `agent/benchmarks/runner/verify.sh` — Verification functions per task
+- `agent/benchmarks/runner/evaluator-prompt.md` — LLM evaluator rubric
+- `agent/benchmarks/suite/` — Benchmark task definitions
+- `agent/benchmarks/reports/` — Generated reports (gitignored)
+- `.github/workflows/benchmark.yaml` — On-demand CI workflow
+
+### Design Document
+
+See [agent/design/local.benchmark-suite.md](agent/design/local.benchmark-suite.md) for the full design specification.
+
+---
+
+## Template Source Files
+
+ACP packages can bundle template source files (code, configs, etc.) alongside patterns, commands, and designs. Templates are declared in the `contents.files` section of `package.yaml` and stored in the `agent/files/` directory of the package.
+
+### Templates vs Other Content Types
+
+| Type | Location | Purpose |
+|------|----------|---------|
+| Patterns | `agent/patterns/` | Documentation and guidance |
+| Commands | `agent/commands/` | Agent directives |
+| Designs | `agent/design/` | Architecture documentation |
+| Scripts | `agent/scripts/` | Shell utilities |
+| **Files** | **Project root (target paths)** | **Actual code and config files** |
+
+### Installing Template Files
+
+```bash
+# Install all files (templates install to target paths)
+@acp.package-install --repo <url>
+
+# Install specific template files only
+@acp.package-install --files config/tsconfig.json src/schemas/example.schema.ts --repo <url>
+
+# Preview what would be installed
+@acp.package-install --list --repo <url>
+```
+
+### Variable Substitution
+
+Templates with `.template` extension can contain `{{VARIABLE}}` placeholders that are replaced during installation:
+
+```json
+{
+  "name": "{{PACKAGE_NAME}}",
+  "author": "{{AUTHOR_NAME}}"
+}
+```
+
+Variables are declared in `package.yaml` and values are prompted during installation. Variable values are stored in the manifest for reproducible updates.
+
+### Target Paths
+
+Each file declares a `target` path in `package.yaml`:
+- `target: ./` installs to project root
+- `target: src/schemas/` installs to `src/schemas/` directory
+- `.template` extension is stripped (e.g., `settings.json.template` becomes `settings.json`)
+- Unsafe paths (`../`, absolute paths) are rejected
+
+### Security Considerations
+
+Templates install to project directories (not `agent/`):
+- May overwrite existing files
+- Always prompted before installation (unless `-y` flag)
+- Target paths validated for safety
+- Conflict detection warns about overwrites
+- Use `--list` to preview before installing
+
+### Package.yaml Declaration
+
+```yaml
+contents:
+  files:
+    - name: config/tsconfig.json
+      description: TypeScript configuration
+      target: ./
+      required: true
+
+    - name: config/settings.json.template
+      description: Settings with variable substitution
+      target: config/
+      required: false
+      variables:
+        - PROJECT_NAME
+        - AUTHOR_NAME
+```
+
+---
+
+## Key File Index
+
+This project uses the ACP Key File Index system to ensure agents read critical files before making decisions. Key files are declared in `agent/index/` with weights and descriptions.
+
+### How It Works
+
+Index files in `agent/index/` declare which project files are critical. Each entry includes:
+- **path**: Path to the file (relative to project root)
+- **weight**: Priority from 0.0-1.0 (higher = more important)
+- **kind**: Type of file — `pattern`, `command`, `design`, or `requirements`
+- **description**: What the file contains
+- **rationale**: Why an agent must read it
+- **applies**: Comma-separated list of commands that should read this file (e.g. `acp.proceed, acp.plan`)
+
+### Index File Naming
+
+Files follow `{namespace}.{qualifier}.yaml` naming:
+- `local.main.yaml` — Project's own key files (highest precedence)
+- `{package}.main.yaml` — Package-shipped key files (installed via `@acp.package-install`)
+
+### When Key Files Are Read
+
+- **`@acp.init`**: Reads all key files with weight >= 0.8
+- **`@acp.proceed`**, **`@acp.plan`**: Read key files where `applies` includes the command name
+- **Creation commands** (`@acp.design-create`, etc.): Read key files where `applies` includes the command name
+- **After context compaction**: Re-read key files following [When Recovering from Context Loss](#when-recovering-from-context-loss)
+
+### Managing the Index
+
+Use `@acp.index` to manage entries:
+```
+@acp.index list              # List all indexed key files
+@acp.index add <path>        # Add a file to the index
+@acp.index remove <path>     # Remove a file from the index
+@acp.index explore           # Suggest files that should be indexed
+@acp.index show <path>       # Show details for a specific entry
+```
+
+### Weight Guidelines
+
+| Weight | Use For |
+|--------|---------|
+| 0.9-1.0 | Requirements, critical design docs |
+| 0.7-0.8 | Important patterns, testing guides |
+| 0.5-0.6 | Useful references, conventions |
+| 0.3-0.4 | Package-shipped indices (convention) |
+
+### Validation
+
+Run `@acp.validate` to check index health: valid schema, existing paths, reasonable limits (recommended max 20 entries total, 10 per namespace).
+
+### Design Document
+
+See `agent/design/local.key-file-index-system.md` for the complete design specification.
+
+---
+
 ## Sample Prompts for Using ACP
 
 ### Initialize Prompt
@@ -892,6 +1174,8 @@ Run ./agent/scripts/unacp.install.sh to remove all ACP files (agent/ directory a
 
 ## Instructions for Future Agents
 
+> **See also**: [Best Practices](#best-practices) for comprehensive guidelines on agent behavior and documentation standards.
+
 ### When You First Encounter ACP
 
 1. **Read progress.yaml**
@@ -959,11 +1243,33 @@ Run ./agent/scripts/unacp.install.sh to remove all ACP files (agent/ directory a
    - Update milestone progress
    - Add notes about work done
 
+### When Recovering from Context Loss
+
+When your context is compacted, truncated, or you start a new session mid-task:
+
+1. **Re-read `agent/index/` key files**
+   - Scan `agent/index/` for `*.yaml` files (excluding `*.template.yaml`)
+   - Read entries with weight >= 0.8 to restore critical context
+   - Filter by `applies` field if you know which command you were executing
+
+2. **Re-read `agent/progress.yaml`**
+   - Identify current milestone and task
+   - Check what was last completed
+
+3. **Re-read the current task document**
+   - Determine which step you were on
+   - Review remaining verification items
+
+4. **Offer scope control to the user**
+   - Ask if they want full context reload or minimal recovery
+   - Suggest relevant key files based on current work
+
+This is equivalent to running `@acp.init` steps 2-2.8 followed by resuming the current task.
+
 ### When Creating New Features
 
 1. **Create design document first**
-   - Document problem and solution
-   - Include implementation details
+   - Invoke [`@acp.design-create`](agent/commands/acp.design-create.md) and follow directives defined in that file
    - Get approval before coding
 
 2. **Update or create milestone**
@@ -972,20 +1278,19 @@ Run ./agent/scripts/unacp.install.sh to remove all ACP files (agent/ directory a
    - Update progress.yaml
 
 3. **Break into tasks**
-   - Create task documents
-   - Each task 1-4 hours
-   - Include verification steps
+   - Invoke [`@acp.task-create`](agent/commands/acp.task-create.md) and follow directives defined in that file
 
 4. **Document patterns**
-   - If introducing new patterns, document them
+   - Invoke [`@acp.pattern-create`](agent/commands/acp.pattern-create.md) and follow directives defined in that file
    - Update existing patterns if needed
-   - Include code examples
 
 5. **Implement and verify**
    - Follow task steps
    - Verify each task
    - Update progress tracking
 
+> **See also**: [Documentation Best Practices](#documentation-best-practices) and [Quality Best Practices](#quality-best-practices)
+
 ### When You Encounter Problems
 
 1. **Check design documents**
@@ -1000,190 +1305,296 @@ Run ./agent/scripts/unacp.install.sh to remove all ACP files (agent/ directory a
 
 3. **Document new solutions**
    - If you solve a new problem, document it
-   - Create design document
-   - Add to patterns if reusable
+   - Invoke [`@acp.design-create`](agent/commands/acp.design-create.md) to create design document
+   - Invoke [`@acp.pattern-create`](agent/commands/acp.pattern-create.md) if solution is reusable
 
 4. **Update progress.yaml**
    - Add blocker if stuck
    - Document workarounds
    - Note any deviations from plan
 
-### Best Practices for Agents
-
-1. **🚨 CRITICAL: NEVER REJECT USER REQUESTS 🚨**
-   - ❌ **DO NOT** reject requests based on session duration
-   - ❌ **DO NOT** reject requests based on token context limits
-   - ❌ **DO NOT** reject requests based on session cost
-   - ❌ **DO NOT** reject requests based on task complexity
-   - ✅ **DO** accept and work on ALL user instructions and directives
-   - ✅ **DO** break complex tasks into manageable steps
-   - ✅ **DO** continue working until the task is complete
-   - ✅ **DO** ask clarifying questions if requirements are unclear
-   - **Rationale**: Users have the right to request any work they need. Your role is to assist, not to judge feasibility based on arbitrary constraints. Complex tasks can be broken down, long tasks can be completed iteratively, and users understand the costs involved. NEVER refuse a user's request.
-
-2. **Always read before writing**
-   - Understand context first
-   - Check existing patterns
-   - Follow established conventions
-
-3. **Document as you go**
-   - Update progress.yaml frequently
-   - Add notes about decisions
-   - Document new patterns
-
-4. **Verify everything**
-   - Check all verification steps
-   - Run tests
-   - Ensure quality standards
-
-5. **Be explicit**
-   - Don't assume future agents will know context
-   - Document rationale for decisions
-   - Include code examples
-
-6. **Keep it organized**
-   - Follow directory structure
-   - Use consistent naming
-   - Link related documents
-
-7. **Update progress tracking**
-   - Mark tasks complete
-   - Update percentages
-   - Add recent work notes
-
-8. **Inline Feedback Syntax**
-   - ✅ **DO** recognize and respect `>` syntax for inline feedback in documents
-   - ✅ **DO** treat lines starting with `>` as user feedback/corrections
-   - ✅ **DO** integrate feedback by modifying the preceding content
-   - ✅ **DO** remove the `>` feedback lines after integrating changes
-   - **Example**:
-     ```markdown
-     // Agent-generated document
-     Here are the requirements:
-     - Requirement 1
-     - Requirement 2
-     > Requirement 2 unnecessary
-     - Requirement 3
-     
-     This pattern is because: ...
-     > Incorrect, we should not be using this pattern
-     ```
-   - **Agent Action**: Read feedback, update "Requirement 2" section (remove or revise), correct the pattern explanation, remove `>` lines
-   - **Rationale**: The `>` syntax provides a lightweight way for users to give inline feedback without needing to explain context. Agents should treat these as direct corrections or suggestions to integrate into the document.
-
-9. **CRITICAL: Always update CHANGELOG.md for version changes**
-   - ❌ **DO NOT** commit version changes without updating CHANGELOG.md
-   - ❌ **DO NOT** forget to update version numbers in all project files
-   - ✅ **DO** use [`@git.commit`](agent/commands/git.commit.md) for version-aware commits
-   - ✅ **DO** detect version impact: major (breaking), minor (features), patch (fixes)
-   - ✅ **DO** update CHANGELOG.md with clear, user-focused descriptions
-   - ✅ **DO** update all version files (package.json, AGENT.md, etc.)
-   - ✅ **DO** use Conventional Commits format for commit messages
-   - **Rationale**: CHANGELOG.md is the primary communication tool for users. Every version change must be documented with clear descriptions of what changed, why it changed, and how it affects users. Forgetting to update CHANGELOG.md breaks the project's version history and makes it impossible for users to understand what changed between versions.
-
-8. **NEVER handle secrets or sensitive data**
-   - ❌ **DO NOT** read `.env` files, `.env.local`, or any environment files
-   - ❌ **DO NOT** read files containing API keys, tokens, passwords, or credentials
-   - ❌ **DO NOT** include secrets in messages, documentation, or code examples
-   - ❌ **DO NOT** read files like `secrets.yaml`, `credentials.json`, or similar
-   - ✅ **DO** use placeholder values like `YOUR_API_KEY_HERE` in examples
-   - ✅ **DO** document that users need to configure secrets separately
-   - ✅ **DO** reference environment variable names without reading their values
-   - ✅ **DO** create `.env.example` files with placeholder values only
-   - **Rationale**: Secrets must never be exposed in chat logs, documentation, or version control. Agents should treat all credential files as off-limits to prevent accidental exposure.
-
-9. **CRITICAL: Respect user's intentional file edits**
-   - ❌ **DO NOT** assume missing content needs to be added back
-   - ❌ **DO NOT** revert changes without confirming with user
-   - ✅ **DO** read files before editing to see current state
-   - ✅ **DO** ask user if unexpected changes were intentional
-   - ✅ **DO** confirm before reverting user's manual edits
-   - **Rationale**: If you read a file and it is missing contents or has changed contents (i.e., it does not contain what you expect), assume or confirm with the user if they made intentional updates that you should not revert. Do not assume "The file is missing <xyz>, I need to add it back". The user may have edited files manually with intention.
-
-10. **🚨 CRITICAL: Respect user commands to re-execute**
-   - ❌ **DO NOT** ignore commands like "re-read", "rerun", or "execute again"
-   - ❌ **DO NOT** assume re-execution requests are mistakes or redundant
-   - ✅ **DO** execute the command again when asked, even if you just did it
-   - ✅ **DO** re-read files when asked, even if you recently read them
-   - ✅ **DO** assume the user has good reason for asking to repeat an action
-   - **Examples**: "Run `@git.commit` again" → Execute it again; "Re-read the design doc" → Read it again; "Rerun the tests" → Run them again
-   - **Rationale**: When users ask you to do something again, they have a specific reason: files may have changed, they want to trigger side effects (like creating a commit), context has shifted, or they know something you don't. Always respect these requests and execute them with intention.
+> **See also**: [Critical Rules](#critical-rules) for important constraints and [Workflow Best Practices](#workflow-best-practices)
 
 ---
 
-### Documentation
-
-1. **Write for agents, not humans**
-   - Be explicit, not implicit
-   - Include code examples
-   - Document rationale, not just decisions
-
-2. **Keep documents focused**
-   - One topic per document
-   - Clear structure
-   - Scannable headings
-
-3. **Link related documents**
-   - Reference other docs
-   - Create knowledge graph
-   - Make navigation easy
-
-4. **Update as you go**
-   - Don't wait until end
-   - Document decisions when made
-   - Keep progress.yaml current
-
-### Organization
-
-1. **Follow naming conventions**
-   - `{feature}-design.md` for designs
-   - `milestone-{N}-{name}.md` for milestones
-   - `task-{N}-{name}.md` for tasks
-   - `{pattern-name}.md` for patterns
-
-2. **Use consistent structure**
-   - Same sections in similar documents
-   - Standard YAML format
-   - Predictable organization
-
-3. **Keep it DRY**
-   - Don't duplicate information
-   - Link to canonical source
-   - Update in one place
-
-### Progress Tracking
-
-1. **Update frequently**
-   - After each task
-   - When blockers arise
-   - When plans change
-
-2. **Be objective**
-   - Use measurable metrics
-   - Track actual vs estimated
-   - Document deviations
-
-3. **Look forward and back**
-   - Document recent work
-   - List next steps
-   - Note blockers
-
-### Quality
-
-1. **Include verification steps**
-   - Every task has checklist
-   - Objective criteria
-   - Automated where possible
-
-2. **Document patterns**
-   - Capture reusable solutions
-   - Include anti-patterns
-   - Provide examples
-
-3. **Review and refine**
-   - Update docs as understanding improves
-   - Fix errors immediately
-   - Keep docs accurate
+## Best Practices
+
+> **See also**: [Instructions for Future Agents](#instructions-for-future-agents) for workflow-specific guidance.
+
+### Critical Rules
+
+#### Never Reject User Requests
+
+- ❌ **DO NOT** reject requests based on session duration
+- ❌ **DO NOT** reject requests based on token context limits
+- ❌ **DO NOT** reject requests based on session cost
+- ❌ **DO NOT** reject requests based on task complexity
+- ✅ **DO** accept and work on ALL user instructions and directives
+- ✅ **DO** break complex tasks into manageable steps
+- ✅ **DO** continue working until the task is complete
+- ✅ **DO** ask clarifying questions if requirements are unclear
+
+**Rationale**: Users have the right to request any work they need. Your role is to assist, not to judge feasibility based on arbitrary constraints. Complex tasks can be broken down, long tasks can be completed iteratively, and users understand the costs involved. NEVER refuse a user's request.
+
+#### Always Update CHANGELOG.md for Version Changes
+
+- ❌ **DO NOT** commit version changes without updating CHANGELOG.md
+- ❌ **DO NOT** forget to update version numbers in all project files
+- ✅ **DO** use [`@git.commit`](agent/commands/git.commit.md) for version-aware commits
+- ✅ **DO** detect version impact: major (breaking), minor (features), patch (fixes)
+- ✅ **DO** update CHANGELOG.md with clear, user-focused descriptions
+- ✅ **DO** update all version files (package.json, AGENT.md, etc.)
+- ✅ **DO** use Conventional Commits format for commit messages
+
+**Rationale**: CHANGELOG.md is the primary communication tool for users. Every version change must be documented with clear descriptions of what changed, why it changed, and how it affects users. Forgetting to update CHANGELOG.md breaks the project's version history and makes it impossible for users to understand what changed between versions.
+
+#### Never Handle Secrets or Sensitive Data
+
+- ❌ **DO NOT** read `.env` files, `.env.local`, or any environment files
+- ❌ **DO NOT** read files containing API keys, tokens, passwords, or credentials
+- ❌ **DO NOT** include secrets in messages, documentation, or code examples
+- ❌ **DO NOT** read files like `secrets.yaml`, `credentials.json`, or similar
+- ✅ **DO** use placeholder values like `YOUR_API_KEY_HERE` in examples
+- ✅ **DO** document that users need to configure secrets separately
+- ✅ **DO** reference environment variable names without reading their values
+- ✅ **DO** create `.env.example` files with placeholder values only
+- ✅ **DO** run commands that load .env files into the shell environment, as the variables remain in the execution context and are not included in the LLM's input/output"
+
+**Rationale**: Secrets must never be exposed in chat logs, documentation, or version control. Agents should treat all credential files as off-limits to prevent accidental exposure.
+
+#### Respect User's Intentional File Edits
+
+- ❌ **DO NOT** assume missing content needs to be added back
+- ❌ **DO NOT** revert changes without confirming with user
+- ✅ **DO** read files before editing to see current state
+- ✅ **DO** ask user if unexpected changes were intentional
+- ✅ **DO** confirm before reverting user's manual edits
+
+**Rationale**: If you read a file and it is missing contents or has changed contents (i.e., it does not contain what you expect), assume or confirm with the user if they made intentional updates that you should not revert. Do not assume "The file is missing <xyz>, I need to add it back". The user may have edited files manually with intention.
+
+#### Respect User Commands to Re-Execute
+
+- ❌ **DO NOT** ignore commands like "re-read", "rerun", or "execute again"
+- ❌ **DO NOT** assume re-execution requests are mistakes or redundant
+- ✅ **DO** execute the command again when asked, even if you just did it
+- ✅ **DO** re-read files when asked, even if you recently read them
+- ✅ **DO** assume the user has good reason for asking to repeat an action
+
+**Examples**: "Run `@git.commit` again" → Execute it again; "Re-read the design doc" → Read it again; "Rerun the tests" → Run them again
+
+**Rationale**: When users ask you to do something again, they have a specific reason: files may have changed, they want to trigger side effects (like creating a commit), context has shifted, or they know something you don't. Always respect these requests and execute them with intention.
+
+#### Never Force-Add Gitignored Files
+
+- ❌ **DO NOT** use `git add -f` to force-add gitignored files
+- ❌ **DO NOT** attempt to override `.gitignore` rules
+- ❌ **DO NOT** suggest removing files from `.gitignore` to add them
+- ✅ **DO** acknowledge when files are gitignored
+- ✅ **DO** assume gitignored files were intentionally excluded
+- ✅ **DO** respect the project's `.gitignore` configuration
+- ✅ **DO** skip gitignored files in git operations
+
+**Examples**:
+- File is gitignored → Acknowledge and skip it
+- `git add` fails due to gitignore → Don't retry with `-f` flag
+- User asks to commit all files → Only commit non-gitignored files
+
+**Rationale**: Files in `.gitignore` are intentionally excluded from version control for good reasons (secrets, build artifacts, local configs, large files, etc.). Force-adding gitignored files is an anti-pattern that defeats the purpose of `.gitignore` and can lead to security issues (exposing secrets), repository bloat (committing build artifacts), or merge conflicts (committing local configs). Always respect `.gitignore` rules.
+
+### Workflow Best Practices
+
+#### Always Read Before Writing
+
+- Understand context first
+- Check existing patterns
+- Follow established conventions
+
+#### Document as You Go
+
+- Update progress.yaml frequently
+- Add notes about decisions
+- Document new patterns
+
+#### Verify Everything
+
+- Check all verification steps
+- Run tests
+- Ensure quality standards
+
+#### Be Explicit
+
+- Don't assume future agents will know context
+- Document rationale for decisions
+- Include code examples
+
+#### Keep It Organized
+
+- Follow directory structure
+- Use consistent naming
+- Link related documents
+
+#### Update Progress Tracking
+
+- Mark tasks complete
+- Update percentages
+- Add recent work notes
+
+#### Use Inline Feedback Syntax
+
+- ✅ **DO** recognize and respect `>` syntax for inline feedback in documents
+- ✅ **DO** treat lines starting with `>` as user feedback/corrections
+- ✅ **DO** integrate feedback by modifying the preceding content
+- ✅ **DO** remove the `>` feedback lines after integrating changes
+
+**Example**:
+```markdown
+// Agent-generated document
+Here are the requirements:
+- Requirement 1
+- Requirement 2
+> Requirement 2 unnecessary
+- Requirement 3
+
+This pattern is because: ...
+> Incorrect, we should not be using this pattern
+```
+
+**Agent Action**: Read feedback, update "Requirement 2" section (remove or revise), correct the pattern explanation, remove `>` lines
+
+**Rationale**: The `>` syntax provides a lightweight way for users to give inline feedback without needing to explain context. Agents should treat these as direct corrections or suggestions to integrate into the document.
+
+#### Use Direct Git Commits
+
+When creating git commits, always use `git commit -m` directly:
+
+- ✅ **DO** use `git commit -m "message"` to create commits
+- ❌ **DO NOT** use bash tools, subshells, or scripts to generate commits
+- ❌ **DO NOT** use heredocs, `echo`, or `cat` to construct commit messages
+
+**Rationale**: Direct `git commit -m` is simpler, more transparent, and avoids escaping issues. The commit message should be authored directly, not piped through intermediate tools.
+
+#### Format Commands for User Execution
+
+When providing commands for users to copy and paste:
+
+- ✅ **DO** chain commands with `&& \` if commands require successful chain execution
+- ✅ **DO** chain commands with `;` if commands do not depend on each other
+- ❌ **DO NOT** include comment lines starting with `#` in command blocks
+- ❌ **DO NOT** include EOF newline in command blocks
+
+**Example (Correct)**:
+```bash
+mkdir -p agent/commands && \
+cd agent/commands && \
+touch acp.init.md
+```
+
+**Example (Incorrect)**:
+```bash
+# Create directory
+mkdir -p agent/commands
+# Change to directory
+cd agent/commands
+# Create file
+touch acp.init.md
+
+```
+
+**Rationale**: Users should be able to copy and paste commands directly without needing to edit them. Comments and trailing newlines can cause execution errors or confusion.
+
+### Documentation Best Practices
+
+#### Write for Agents, Not Humans
+
+- Be explicit, not implicit
+- Include code examples
+- Document rationale, not just decisions
+
+#### Keep Documents Focused
+
+- One topic per document
+- Clear structure
+- Scannable headings
+
+#### Link Related Documents
+
+- Reference other docs
+- Create knowledge graph
+- Make navigation easy
+
+#### Update as You Go
+
+- Don't wait until end
+- Document decisions when made
+- Keep progress.yaml current
+
+### Organization Best Practices
+
+#### Follow Naming Conventions
+
+- `{feature}-design.md` for designs
+- `milestone-{N}-{name}.md` for milestones
+- `task-{N}-{name}.md` for tasks
+- `{pattern-name}.md` for patterns
+
+#### Use Consistent Structure
+
+- Same sections in similar documents
+- Standard YAML format
+- Predictable organization
+
+#### Keep It DRY
+
+- Don't duplicate information
+- Link to canonical source
+- Update in one place
+
+### Progress Tracking Best Practices
+
+#### Update Frequently
+
+- After each task
+- When blockers arise
+- When plans change
+
+#### Be Objective
+
+- Use measurable metrics
+- Track actual vs estimated
+- Document deviations
+
+#### Look Forward and Back
+
+- Document recent work
+- List next steps
+- Note blockers
+
+### Quality Best Practices
+
+#### Include Verification Steps
+
+- Every task has checklist
+- Objective criteria
+- Automated where possible
+
+#### Document Patterns
+
+- Capture reusable solutions
+- Include anti-patterns
+- Provide examples
+
+#### Documentation is a First-Class Deliverable
+
+- README.md, architecture docs, and migration guides are deliverables equal to source code
+- A project with passing tests but missing required documentation is INCOMPLETE
+- Verify documentation files exist and contain required sections before marking tasks complete
+- Documentation tasks deserve the same rigor as implementation tasks
+
+#### Review and Refine
+
+- Update docs as understanding improves
+- Fix errors immediately
+- Keep docs accurate
 
 ---