AGENTS.md

1. Interaction Protocol

Interaction must occur exclusively via ask_user tool, always iterative, interactive, and with no iteration limits.

Each iteration must:

• Ask exactly one clear question
• Provide 6 options total:
  • 3 structured options
  • 1 always-present Freeform option
  • 1 always-present Autonomous Mode option
  • 1 always-present I'm satisfied option
• Explicitly indicate which option is the most future-proof

Mandatory Option Set

Every ask_user call must include:

1. Structured Option A
2. Structured Option B
3. Structured Option C
4. Freeform
5. Autonomous Mode
6. I'm satisfied — terminates the feedback loop

Autonomous Mode

Autonomous Mode means:

• Work autonomously until all milestones are completed
• Always choose the best, most future-proof option among the available alternatives
• Request feedback only after all milestones have been completed
• Ask for confirmation only if strictly necessary (destructive, irreversible, or high-risk actions)

Feedback Loop Termination

The interaction is a continuous feedback loop. It stops only when the user explicitly selects:

"I'm satisfied"

This option must be always present as the last option in every ask_user call. Until the user explicitly chooses it, the loop must continue indefinitely — proposing new improvements, refinements, or next steps. No implicit completion is allowed. The agent must never assume the user is satisfied unless this option is explicitly selected.

2. Planning & Continuous Tracking

A plan must always be:

• Created before execution
• Continuously updated
• Accompanied by a concise progress summary after each update

Mandatory Plan Schema

interface Plan {
  PRD: string;
  context: string;
  milestones: Record<string, Milestone>;
}

interface Milestone {
  id: string;                          // e.g. "m1"
  description: string;
  priority: "critical" | "high" | "medium" | "low";
  status: "todo" | "in_progress" | "review" | "done";
  depends_on: string[];                // milestone IDs
  issues: Record<string, Issue>;
}

interface Issue {
  id: string;                          // e.g. "i1"
  task: string;
  priority: "critical" | "high" | "medium" | "low";
  status: "todo" | "in_progress" | "review" | "done" | "blocked";
  depends_on: string[];                // issue IDs
  children: Record<string, Issue>;
}

Structural Rules

• Milestones and issues are hierarchical.
• The structure must enable parallel work when possible.
• Each milestone must have a unique id.
• Each issue must have a unique id.
• Every issue must explicitly declare dependencies using depends_on.
• Issues may contain nested child issues.
• The dependency graph must allow safe parallelization.

Milestone Execution Order

Milestones must be executed respecting:

1. Dependency order — a milestone with depends_on cannot start until all dependencies are done.
2. Priority — among independent milestones, execute critical → high → medium → low.
3. Parallelism — independent milestones with the same priority may be executed in parallel.

Milestone Completion

A milestone is done when all its issues are done. After merging all issue work into the milestone branch, run a final integration verification (build + full test suite) on the merged result. Must pass with zero errors and zero warnings.

Issue Completion Gate (Definition of Done)

An issue cannot be marked as done until it passes a code review feedback loop and meets all criteria below:

Review Gate

1. Run a full code review (linting, type-checking, build verification, and static analysis).
2. The review must report zero errors and zero warnings.
3. If any error or warning is found, fix it and restart the review from step 1.
4. The issue is complete only after two consecutive reviews pass with zero errors and zero warnings.

This gate is mandatory — no issue may be closed or considered done without meeting this criteria.

Additional Criteria

• Implementation complete and follows architectural principles
• Unit tests written and passing
• Integration tests written and passing (if applicable)
• E2E tests written and passing (if the change affects user-facing flows)
• Regression tests passing (no previously passing test broken)
• Test coverage has not decreased compared to baseline
• Code is self-documenting or has inline comments where non-obvious
• Corresponding GitHub Issue updated with status and relevant notes

3. GitHub Project Sync

The local plan must be mirrored on GitHub at all times. GitHub is the single source of truth for project tracking.

Milestones

• Every plan milestone must have a corresponding GitHub Milestone.
• GitHub Milestone title: M<id> — <description> (e.g. M1 — Project Setup).
• GitHub Milestone description must include: priority, dependencies, and acceptance criteria.
• Milestone due dates should be set when applicable.

Issues

• Every plan issue must have a corresponding GitHub Issue.
• GitHub Issue title: [M<milestone_id>] I<issue_id> — <task> (e.g. [M2] I3 — Implement JWT auth).
• Issues must include:
  • Labels: priority (P-critical, P-high, P-medium, P-low), type (feat, fix, refactor, chore, test), and status (in-progress, review, blocked).
  • Milestone: linked to corresponding GitHub Milestone.
  • Dependencies: referenced in the issue body using depends on #<issue_number>.
  • Parent/child: child issues reference parent with part of #<issue_number>.

Sync Rules

• When a plan is created or updated, corresponding GitHub Milestones and Issues must be created or updated.
• When an issue status changes locally, the GitHub Issue must be updated immediately.
• When all issues in a milestone are done, the GitHub Milestone must be closed.
• Labels must be kept in sync with plan status at all times.
• No orphan issues — every GitHub Issue must belong to a Milestone.

Why Not Linear

GitHub Issues + Milestones + Labels is sufficient for single-developer and small-team projects. Adding Linear would introduce unnecessary synchronization overhead without proportional benefit. If the project scales to multiple teams with complex sprint planning, reconsider adopting Linear via MCP integration.

4. Testing Policy

All code must be tested before it can pass the Issue Completion Gate.

Requirements

• Unit tests are mandatory for all business logic, utilities, and pure functions.
• Integration tests are mandatory for API routes, database interactions, and cross-module flows.
• E2E tests are mandatory for all user-facing flows and critical paths.
• Non-regression tests are mandatory — no previously passing test may break as a result of new changes, and test coverage must not decrease.
• All tests must pass with zero failures before an issue review can begin.

E2E Test Rules

End-to-end tests validate complete flows across the full system — whether they involve a UI, an API, a CLI, or any other entry point.

Execution Skill: Detailed execution procedures are defined in .agent/skills/e2e-testing/SKILL.md. The agent must read and follow that skill before writing or running E2E tests.

Scope

• Every critical flow must have at least one E2E test (e.g., login, registration, main CRUD operations, API workflows, CLI commands).
• E2E tests must cover happy paths and the most important error/edge cases for each flow.
• When an issue modifies a flow, E2E tests for that flow must be added or updated.

Execution

• E2E tests must be executed programmatically — never manually.
• Primary method: CLI — run via project test scripts (e.g., test:e2e), capturing exit codes and structured output.
• Complementary method: MCP tools — use available MCP tools (browser automation, DevTools, framework-specific tools) for runtime verification when applicable.
• MCP-driven verification is complementary, not a substitute for the automated test suite.
• Choose the E2E testing tool most appropriate for the project type and stack.
• If the project spans multiple layers (e.g., frontend + API), each layer must have its own E2E tests.

Requirements

• Tests must run in non-interactive mode for CI compatibility.
• Tests must be deterministic — avoid flaky timeouts, seed test data when needed, use stable identifiers.
• Tests must be independent — each test must set up and tear down its own state.
• E2E tests must run as part of the CI pipeline and pass before merge.

Organization

• E2E tests reside in a dedicated e2e/ or tests/e2e/ directory.
• Group tests by feature or user flow.

Non-Regression Test Rules

Non-regression testing ensures that new changes do not break existing functionality and that quality does not degrade over time.

Baseline & Comparison

• Before starting work on any issue, run the full test suite (unit + integration + E2E) and record the baseline:
  • Total tests, passing tests, failing tests.
  • Code coverage percentage (line and branch).
• After completing work, run the full test suite again and produce a diff report:
  • Tests added, tests removed, tests broken.
  • Coverage delta.

Non-Regression Rules

• If any previously passing test now fails, the issue cannot be marked as done until the regression is fixed.
• Test coverage must not decrease — if coverage drops, new tests must be added to restore or exceed the baseline.
• Regression fixes must not introduce new regressions (recursive verification).
• When fixing a bug, a regression test for that specific bug must be added to prevent recurrence.

Principles

• Tests must be deterministic, isolated, and repeatable.
• No test may depend on external services unless explicitly mocked.
• Test names must clearly describe the expected behavior.
• Edge cases and error paths must be covered, not just happy paths.
• Prefer data-testid attributes for E2E selectors over CSS classes or DOM structure.

5. Session Logging

For each working session, create or update:

sessions-<ISO-date>.md

Format

# Session <ISO date>

## Status
Milestones: m1 (done), m2 (in_progress), m3 (todo)

## Work Completed
- [m2/i1] Implemented authentication flow
- [m2/i2] Fixed type errors in user model

## Completion Gate Passed
- [m2/i1] ✅ 2 consecutive passes
- [m2/i2] ✅ 2 consecutive passes

## Decisions Made
- Chose JWT over session-based auth (see doc-first analysis)

## Blockers
- None | <describe blocker and status>

## GitHub Sync
- Created: #12, #13
- Closed: #10, #11
- Updated: #14 (status → in_progress)

## Branch
feat/m2-authentication

## Date
<ISO timestamp>

Session logging is mandatory and must accurately reflect progress.

6. Git Workflow

Authorship

All commits and contributions must be authored exclusively by the repository owner. No co-authors are permitted. Git config must reflect the sole author:

# Ensure no co-author trailers are added
# Every commit must have exactly one author: the repo owner
git config user.name "<owner-name>"
git config user.email "<owner-email>"

Commits must never include Co-authored-by trailers or any attribution to other entities (including AI agents).

Branch Strategy

For every milestone or major phase:

• Create a dedicated branch with its own git worktree (git worktree add)
• Each worktree provides an isolated working directory, enabling safe parallel work by multiple subagents
• Maintain traceability between worktrees, branches, milestones, and issues

# Example: create a worktree for milestone m2
git worktree add ../project-m2 -b feat/m2-authentication

Branch Naming Convention

<type>/<milestone-id>-<short-description>

Types:

Examples:

• feat/m1-project-setup
• fix/m2-i3-login-redirect
• refactor/m4-hexagonal-migration

Commit Convention

All commits must follow Conventional Commits format, referencing the issue ID:

<type>(<scope>): <description>

Refs: #<github-issue-number>

Examples:

feat(auth): implement JWT token generation

Refs: #12

fix(m2-i3): resolve login redirect loop

Refs: #15

Rules:

• One logical change per commit.
• Commit message must be clear and self-explanatory.
• Always reference the related GitHub Issue.
• Never include Co-authored-by trailers.

Pull Request Policy

Every milestone branch must be merged via Pull Request:

• PR title: M<id> — <milestone description>
• PR body must include:
  • Summary of changes
  • List of related issues (auto-close syntax: Closes #12, Closes #13)
  • Confirmation that all issues passed their Completion Gate (two consecutive reviews each)
  • Test results summary
• All issues must have passed the Completion Gate before merge.
• Squash merge is preferred for clean history.

Structural Change Policy

If unexpected architectural or structural changes emerge:

• Stop immediately
• Use ask_user before proceeding

No unapproved structural deviation is allowed.

7. Architectural Principles & Future-Proof Strategy

Design Principles

Always apply:

• KISS — Keep it simple
• DRY — Don't repeat yourself
• SOLID — Single responsibility, Open/closed, Liskov, Interface segregation, Dependency inversion
• Hexagonal Architecture (Ports & Adapters)

Strategic Requirements

Every decision must:

• Maximize extensibility
• Minimize technical debt
• Preserve architectural coherence
• Support long-term system evolution
• Be production-grade by design

Strict Constraints

• No workarounds
• No temporary patches
• No short-term fixes
• No uncontrolled technical debt
• No destructive actions unless necessary
• No tactical shortcuts

Only definitive, scalable, long-term solutions are allowed. Workaround-based solutions are strictly prohibited.

8. Error Handling & Rollback Strategy

When the Completion Gate Fails Repeatedly

If an issue fails the Completion Gate 3 times consecutively:

1. Stop all work on that issue.
2. Perform a root cause analysis — identify whether the problem is architectural, a dependency issue, or a scope issue.
3. Use ask_user to present findings and propose one of:
   • Rescope — break the issue into smaller, more testable sub-issues.
   • Rollback — revert to the last known good state and re-approach.
   • Redesign — revisit the architectural approach for that component.
4. Do not continue iterating blindly.

Rollback Rules

• Every branch must have a clean, revertible commit history.
• If rollback is chosen, revert to the last commit that passed the Completion Gate for that issue.
• Document the rollback reason in the session log.

9. Subagent Orchestration

Use subagents whenever it improves execution quality, efficiency, or separation of concerns.

Subagents must be considered when:

• Work can be parallelized safely
• Responsibilities can be isolated clearly
• A task requires specialized analysis or implementation
• Independent workstreams reduce execution time
• A milestone or issue can be delegated without breaking dependency constraints

All subagent activity must remain aligned with:

• The current plan
• Milestone and issue dependencies
• Architectural principles
• The future-proof strategy

Batch Tool Execution

When a workflow requires 3+ independent tool calls, prefer programmatic batch execution: generate code that calls tools in a loop, filters/aggregates results, and returns only the summary to the context window. This reduces latency, token consumption, and round-trips. The pattern is provider-agnostic and applies to any LLM-based agent architecture.

Programmatic Code Transformations

When a change affects multiple files or repeated patterns, prefer automated transformations over manual file-by-file edits. Use codemods, AST-based tools (ts-morph, jscodeshift), or batch scripts (sed, awk, custom scripts) whenever possible. Programmatic transformations are faster, deterministic, consistent, and less error-prone than manual editing at scale.

10. Document-First Approach

Before implementing any solution:

• Analyze official documentation
• Use:
  • Documentation retrieval tools (MCP, context7, or equivalent)
  • Web search when required

All decisions must be:

• Documentation-aligned
• Standards-compliant
• Evidence-based
• Verified before implementation

No implementation without prior documentation review.

11. Problem-Solving Framework

When a problem arises:

1. Perform structured root cause analysis
2. Identify the optimal long-term solution
3. Validate against architectural principles
4. Implement cleanly
5. Execute feedback loop (Completion Gate)
6. Fine-tune

If progress stalls:

• Change strategy
• Reassess assumptions
• Avoid technical stubbornness
• Do not persist with ineffective approaches

The objective is full autonomous resolution while preserving architectural integrity, scalability, and long-term system quality.