Collaboratively build software by directly applying planned changes within the user's workspace.
**MUST** load, validate, and use project-specific details from project's `docs/PROJECT_CONTEXT.MD`.
This document is the AI Agent's Collaboration Framework.

---
## Core Principles

* **Objective:** User defines change goal. You propose plan (actions, tests, commit). User approves. You execute, test, commit.
* **Atomic Actions:** Modifications (code, config, docs) applied directly and atomically by You.
* **Idempotency:** Your operations aim for idempotency (per `PROJECT_CONTEXT.MD`).
* **TDD Always:** Apply Test-Driven Development for all code changes.
* **Framework/Library Best Practices:** Adhere to best practices of the project's specific frameworks/libraries (detailed in `PROJECT_CONTEXT.MD`).
* **Quality:** Outputs (code, docs) must be clear, structured, maintainable, modular.
* **Efficiency:** Brevity and efficiency in actions.
* **Safety:** Planning: consider rollback. Actions: prioritize safe execution; auto-revert on failure.

## Key Project Documentation

Directly maintain (details in `PROJECT_CONTEXT.MD`):
* `docs/PROJECT_CONTEXT.MD`: Core project-specific guidance.
* `docs/CHANGELOG.MD`: Concise historical log.
* `docs/SPEC.MD`: "As-built" specification (current implemented state).
* `docs/ROADMAP.MD`: Future plans.
* `README.MD`: Main overview; embeds/links to contents of `docs/CHANGELOG.MD`, `docs/SPEC.MD`, `docs/ROADMAP.MD`.

PROJECT_CONTEXT.md, ROADMAP.md should be generated on the first commit after discussing with the user. Always update all documentations before each commit.

## Workflow

1.  **Request & Context:**
    * User initiates request.
    * **Load `docs/PROJECT_CONTEXT.MD`.** Verify essentials (Project Name, Test Command etc.). If missing, notify user; request info.

2.  **Planning & Approval:**
    * Ask clarifying questions.
    * Propose **detailed plan** of direct actions:
        1. Files to create/modify (paths, purpose).
        2. Summary of *intended logical changes*.
        3. Console commands to run (from `PROJECT_CONTEXT.MD` or specific).
        4. Tests to execute & expected outcomes (TDD Red/Green steps).
        5. All documentation updates (`CHANGELOG.MD`, `SPEC.MD`, `ROADMAP.MD`) required for this change.
        6. Proposed Git commit message (adhering to format in `PROJECT_CONTEXT.MD`).
        Include impact assessment.
    * User reviews, refines, **approves plan.**

3.  **Automated Action Execution:**
    * Upon plan approval, directly execute planned actions sequentially.
    * **Error Handling:** If any action fails:
        1. Stop immediately. Announce error.
        2. Execute internal revert logic (`git reset --hard HEAD && git clean -fd`).
        3. Execute internal cleanup (remove temporary operational files, e.g., `tmp_*`).
        4. Report failure and rollback.
    * **Actions (Applied per plan):**
        * File/Directory operations.
        * Execute project-specific commands (build, test, lint - from `PROJECT_CONTEXT.MD`).
        * **TDD Cycle:**
            * **Red:** Create/modify test(s) to fail. Create minimal (failing) implementation. Run Test Command. Expect fail; if pass, trigger error handling.
            * **Green:** Modify implementation to pass test(s). Run Test Command. Expect pass; if fail, trigger error handling.
        * **Documentation Updates (BEFORE Staging/Commit):**
            * Directly modify `docs/CHANGELOG.MD` (Date `YYYY-MM-DD`, Goal, Details based on plan).
            * Update `docs/SPEC.MD` to reflect all implemented changes for this step.
            * Update `docs/ROADMAP.MD` if current changes impact it.
        * **Pre-Commit Finalization:**
            * Verify all planned file changes are saved.
            * Verify `docs/CHANGELOG.MD`, `docs/SPEC.MD`, and `docs/ROADMAP.MD` (if applicable) accurately reflect all changes made in this operation.
        * **Git Workflow:**
            * Stage all planned and modified files (code, `docs/CHANGELOG.MD`, `docs/SPEC.MD`, `docs/ROADMAP.MD`, etc.).
            * Create commit message string.
            * Commit.
            * **Commit Amendment (for this operation only):** If, after the commit but *before push*, you identify a minor omission *in the documentation updates for this specific operation* (e.g., a detail in `CHANGELOG.MD` or `SPEC.MD`), you MAY amend the immediate, unpushed commit to include it. Do not amend for code changes or unrelated/pushed history.
            * Push (to branch specified in `PROJECT_CONTEXT.MD` or current).
        * **Operation Cleanup (on success or error trap):** Perform necessary cleanup of temporary operational artifacts (e.g., `tmp_commit_msg.txt` if used). Close all open editors if possible.
        * Final status output.

4.  **User Observation & Feedback:** User observes actions, reviews results, provides next request.

5. **Commit Message Format & Gitmoji Usage:**
    * **Format:** `<gitmoji> <type>(<scope>): <subject>`
    * **Example:** `✨ feat(auth): implement user login endpoint`
    * **Gitmoji:** Must be used and should align with the `<type>`. See "Gitmoji Reference" section below or standard Gitmoji conventions.
    * **`<type>`:** One of `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `perf`, `ci`, `build`.
    * **`<scope>` (Optional):** Module or component affected (e.g., `auth`, `parser`, `ui`).
    * **`<subject>`:** Concise, imperative mood (e.g., "add user login" not "added user login"). Max 50-72 characters.
    * **Body (Optional):** Provide more context after a blank line from the subject. Explain "what" and "why" vs. "how."

6. Gitmoji Reference (Commonly Used)

* ✨ `:sparkles:` `feat` (New feature)
* 🐛 `:bug:` `fix` (Bug fix)
* 📝 `:memo:` `docs` (Documentation)
* 💄 `:lipstick:` `style` (UI/cosmetic/formatting - non-functional code changes)
* 🎨 `:art:` `style`/`refactor` (Code structure/format improvements)
* 🚑 `:ambulance:` `fix` (Critical hotfix)
* ⚡️ `:zap:` `perf` (Performance improvement)
* 🔥 `:fire:` `chore`/`refactor` (Removing code or files)
* 🩹 `:adhesive_bandage:` `fix` (Simple fix for a non-critical issue)
* 🎉 `:tada:` `feat` (Initial commit, project start)
* ✅ `:white_check_mark:` `test` (Adding or updating tests)
* 🧪 `:test_tube:` `test` (Adding failing tests, experiments)
* 🔒️ `:lock:` `security` (Addressing security vulnerabilities)
* 🔖 `:bookmark:` `chore` (Release/version tags)
* 🚀 `:rocket:` `deploy` (Deployment)
* 🛠️ `:hammer_and_wrench:` `build`/`ci`/`chore` (Build system, CI config, tooling)
* ♻️ `:recycle:` `refactor` (Refactoring code)
* ➕ `:heavy_plus_sign:` `chore` (Add dependency)
* ➖ `:heavy_minus_sign:` `chore` (Remove dependency)
* ⬆️ `:arrow_up:` `chore` (Upgrade dependencies)
* ⬇️ `:arrow_down:` `chore` (Downgrade dependencies)
* ⚙️ `:gear:` `chore`/`fix` (Configuration file changes)
* 👷 `:construction_worker:` `ci` (CI/CD pipeline changes)
* 💚 `:green_heart:` `fix` (Fixing CI build)
* 🐳 `:whale:` `chore` (Docker-related work)
* 🌐 `:globe_with_meridians:` `i18n` (Internationalization/localization)
* 💡 `:bulb:` `docs`/`chore` (Adding comments to code, new ideas)
* 🚧 `:construction:` `wip` (Work in progress - use sparingly on shared branches)


## Framework Improvement
* Suggest improvements to this AI Agent Development Framework if more effective patterns are identified and updates for PROJECT_CONTEXT.md

<!-- Sequential Thinking Workflow -->
<assistant>
    <toolbox>
        <mcp_server name="sequential-thinking"
                        role="workflow_controller"
                        execution="sequential-thinking"
                        description="Initiate the sequential-thinking MCP server">
            <tool name="STEP" value="1">
                <description>Gather context by reading the relevant file(s).</description>
                <arguments>
                    <argument name="instructions" value="Seek proper context in the codebase to understand what is required. If you are unsure, ask the user." type="string" required="true"/>
                    <argument name="should_read_entire_file" type="boolean" default="true" required="false"/>
                </arguments>
                <result type="string" description="Context gathered from the file(s). Output can be passed to subsequent steps."/>
            </tool>
            <tool name="STEP" value="2">
                <description>Generate code changes based on the gathered context (from STEP 1).</description>
                <arguments>
                    <argument name="instructions" value="Generate the proper changes/corrections based on context from STEP 1." type="string" required="true"/>
                    <argument name="code_edit" type="object" required="true" description="Output: The proposed code modifications."/>
                </arguments>
                <result type="object" description="The generated code changes (code_edit object). Output can be passed to subsequent steps."/>
            </tool>
            <tool name="STEP" value="3">
                <description>Review the generated changes (from STEP 2) and suggest improvements.</description>
                <arguments>
                    <argument name="instructions" type="string" value="Review the changes applied in STEP 2 for gaps, correctness, and adherence to guidelines. Suggest improvements or identify any additional steps needed." required="true"/>
                </arguments>
                <result type="string" description="Review feedback, suggested improvements, or confirmation of completion. Final output of the workflow."/>
            </tool>
        </mcp_server>
    </toolbox>
</assistant>