FOSS/AyuGramDesktop
1
0
Fork 0
mirror of https://github.com/AyuGram/AyuGramDesktop.git synced 2026-07-25 06:54:43 +00:00
Code Issues Packages Projects Releases Wiki Activity

[ai] Try using subagents in Codex.

Browse Source
This commit is contained in:
John Preston
2026-03-20 00:03:54 +07:00
parent 90eda7c03a
commit 0bc9ee3cf1
2 changed files with 242 additions and 265 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/skills/task-think/PROMPTS.md
+203 -225
View File
@@ -1,35 +1,46 @@
# Phase Prompts # Phase Prompts
Use these templates for `codex exec --json` child runs. Replace `<TASK>`, `<PROJECT>`, `<LETTER>`, and `<REPO_ROOT>`. Use these templates as Codex subagent messages or, if delegation is unavailable, as same-session checklists. Replace `<TASK>`, `<PROJECT>`, `<LETTER>`, and `<REPO_ROOT>`.
## Orchestration Rules
- Phase 0 runs in the main session.
- For Phases 1 through 6, prefer a fresh subagent per phase to keep phase context isolated.
- Write each phase prompt to `.ai/<PROJECT>/<LETTER>/logs/phase-<name>.prompt.md` before execution.
- If you delegate a phase, send the prompt file contents as the initial `spawn_agent` message.
- After each phase completes, write `.ai/<PROJECT>/<LETTER>/logs/phase-<name>.result.md` summarizing the status, files touched, and any follow-up notes.
- Use `fork_context: false` by default. If the phase depends on thread-only context or UI attachments, pass that context explicitly or enable `fork_context` only for that phase.
- Prefer `worker` for phases that write files. Use `default` for plan or review passes if that fits the host better. Use `explorer` only for narrow read-only questions.
- When supported, request `model: gpt-5.4` and `reasoning_effort: xhigh` for delegated phases.
- Never use `codex exec`, background shell child processes, or JSONL child-session logging from this skill.
## Phase 0: Setup ## Phase 0: Setup
**Record the current time now** and store it as `$START_TIME`. You will use this at the end to display total elapsed time. Record the current time now and store it as `$START_TIME`. You will use this at the end to display total elapsed time.
Before running any phase prompts, the orchestrator must determine whether this is a new project or a follow-up task. Before running any phase prompts, determine whether this is a new project or a follow-up task.
**Follow-up detection (MANDATORY — do this BEFORE anything else):** Follow-up detection:
1. Extract the first word/token from the task description. Call it `FIRST_TOKEN`. 1. Extract the first word or token from the task description. Call it `FIRST_TOKEN`.
2. Run these two checks IN PARALLEL: 2. Check `.ai/` to see existing project names.
- `ls .ai/` — to see all existing project names 3. Check whether `.ai/<FIRST_TOKEN>/about.md` exists.
- `ls .ai/<FIRST_TOKEN>/about.md` — to check if this specific project exists 4. If the file exists, this is a follow-up task. The project name is `FIRST_TOKEN`. The task description is everything after `FIRST_TOKEN`.
3. If check 2 **succeeds** (the file exists): this is a **follow-up task**. The project name is `FIRST_TOKEN`. The task description is everything after `FIRST_TOKEN`. 5. If the file does not exist, this is a new project. The full input is the task description.
4. If check 2 **fails** (file not found): this is a **new project**. The full input is the task description.
**Do NOT proceed until you have run these checks and determined follow-up vs new.** Do not proceed until you have determined follow-up vs new.
**For new projects:** For new projects:
- Using the list from check 1, pick a unique short name (1-2 lowercase words, hyphen-separated) that doesn't collide with existing projects. - Using the list of existing projects, pick a unique short name (1-2 lowercase words, hyphen-separated) that does not collide.
- Create `.ai/<PROJECT>/` and `.ai/<PROJECT>/a/` and `logs/`. - Create `.ai/<PROJECT>/`, `.ai/<PROJECT>/a/`, and `.ai/<PROJECT>/a/logs/`.
- Set `<LETTER>` = `a`. - Set `<LETTER>` = `a`.
**For follow-up tasks:** For follow-up tasks:
- Scan `.ai/<PROJECT>/` for existing task folders (`a/`, `b/`, ...). Find the latest one (highest letter). - Scan `.ai/<PROJECT>/` for existing task folders (`a/`, `b/`, ...). Find the latest one (highest letter).
- The previous task letter = that highest letter. - The previous task letter = that highest letter.
- The new task letter = next letter in sequence. - The new task letter = next letter in sequence.
- Create `.ai/<PROJECT>/<LETTER>/` and `logs/`. - Create `.ai/<PROJECT>/<LETTER>/` and `.ai/<PROJECT>/<LETTER>/logs/`.
Then proceed to Phase 1. Follow-up tasks do NOT skip context gathering — they go through a modified version of it. Then proceed to Phase 1. Follow-up tasks do not skip context gathering. They use a modified Phase 1F prompt.
## Phase 1: Context (New Project, letter = `a`) ## Phase 1: Context (New Project, letter = `a`)
@@ -38,50 +49,50 @@ You are a context-gathering agent for a large C++ codebase (Telegram Desktop).
TASK: <TASK> TASK: <TASK>
YOUR JOB: Read AGENTS.md, inspect the codebase, find ALL files and code relevant to this task, and write two documents. YOUR JOB: Read AGENTS.md, inspect the codebase, find all files and code relevant to this task, and write two documents.
Steps: Steps:
1. Read AGENTS.md for project conventions and build instructions. 1. Read AGENTS.md for project conventions and build instructions.
2. Search the codebase for files, classes, functions, and patterns related to the task. 2. Search the codebase for files, classes, functions, and patterns related to the task.
3. Read all potentially relevant files. Be thorough - read more rather than less. 3. Read all potentially relevant files. Be thorough and prefer reading more rather than less.
4. For each relevant file, note: 4. For each relevant file, note:
- File path - file path
- Relevant line ranges - relevant line ranges
- What the code does and how it relates to the task - what the code does and how it relates to the task
- Key data structures, function signatures, patterns used - key data structures, function signatures, and patterns used
5. Look for similar existing features that could serve as a reference implementation. 5. Look for similar existing features that could serve as a reference implementation.
6. Check api.tl if the task involves Telegram API. 6. Check api.tl if the task involves Telegram API.
7. Check .style files if the task involves UI. 7. Check .style files if the task involves UI.
8. Check lang.strings if the task involves user-visible text. 8. Check lang.strings if the task involves user-visible text.
Write TWO files: Write two files.
### File 1: .ai/<PROJECT>/about.md File 1: .ai/<PROJECT>/about.md
NOTE: This file is NOT used by any agent in the current task. It exists solely as a starting point for a FUTURE follow-up task's context gatherer. No planning, implementation, or review agent will ever read it. Only the context-gathering agent of the next follow-up task reads about.md (together with the latest context.md) to produce a fresh context.md for that next task. This file is not used by any agent in the current task. It exists solely as a starting point for a future follow-up task's context gatherer. No planning, implementation, or review phase should rely on it during the current task.
Write it as if the project is already fully implemented and working. It should contain: Write it as if the project is already fully implemented and working. It should contain:
- **Project**: What this project does (feature description, goals, scope) - Project: What this project does (feature description, goals, scope)
- **Architecture**: High-level architectural decisions, which modules are involved, how they interact - Architecture: High-level architectural decisions, which modules are involved, how they interact
- **Key Design Decisions**: Important choices made about the approach - Key Design Decisions: Important choices made about the approach
- **Relevant Codebase Areas**: Which parts of the codebase this project touches, key types and APIs involved - Relevant Codebase Areas: Which parts of the codebase this project touches, key types and APIs involved
Do NOT include temporal state like "Current State", "Pending Changes", "Not yet implemented", "TODO", or any other framing that distinguishes between "done" and "not done". Describe the project as a complete, coherent whole — as if everything is already working. This is a project overview, not a status tracker. Task-specific work belongs exclusively in context.md. Do not include temporal state like "Current State", "Pending Changes", "Not yet implemented", or "TODO". Describe the project as a complete, coherent whole.
### File 2: .ai/<PROJECT>/a/context.md File 2: .ai/<PROJECT>/a/context.md
This is the task-specific implementation context. This is the PRIMARY document — all downstream agents (planning, implementation, review) will read ONLY this file. It must be completely self-contained. It should contain: This is the primary task-specific implementation context. All downstream phases should be able to work from this file plus the referenced source files. It must be self-contained. Include:
- **Task Description**: The full task restated clearly - Task Description: The full task restated clearly
- **Relevant Files**: Every file path with line ranges and descriptions of what's there - Relevant Files: Every file path with line ranges and descriptions
- **Key Code Patterns**: How similar things are done in the codebase (with code snippets) - Key Code Patterns: How similar things are done in the codebase, with snippets when useful
- **Data Structures**: Relevant types, structs, classes - Data Structures: Relevant types, structs, classes
- **API Methods**: Any TL schema methods involved (copied from api.tl) - API Methods: Any TL schema methods involved, copied from api.tl when useful
- **UI Styles**: Any relevant style definitions - UI Styles: Any relevant style definitions
- **Localization**: Any relevant string keys - Localization: Any relevant string keys
- **Build Info**: Build command and any special notes - Build Info: Build command and any special notes
- **Reference Implementations**: Similar features that can serve as templates - Reference Implementations: Similar features that can serve as templates
Be extremely thorough. Another agent with NO prior context will read this file and must be able to understand everything needed to implement the task. Be extremely thorough. Another agent with no prior context will rely on this file.
Do not implement code in this phase. Do not implement code in this phase.
``` ```
@@ -97,49 +108,44 @@ YOUR JOB: Read the existing project state, gather any additional context needed,
Steps: Steps:
1. Read AGENTS.md for project conventions and build instructions. 1. Read AGENTS.md for project conventions and build instructions.
2. Read .ai/<PROJECT>/about.md — this is the project-level blueprint describing everything done so far. 2. Read .ai/<PROJECT>/about.md. This is the project-level blueprint describing everything done so far.
3. Read .ai/<PROJECT>/<PREV_LETTER>/context.md — this is the previous task's gathered context. 3. Read .ai/<PROJECT>/<PREV_LETTER>/context.md. This is the previous task's gathered context.
4. Understand what has already been implemented by reading the actual source files referenced in about.md and the previous context. 4. Understand what has already been implemented by reading the actual source files referenced in about.md and the previous context.
5. Based on the NEW TASK description, search the codebase for any ADDITIONAL files, classes, functions, and patterns that are relevant to the new task but not already covered. 5. Based on the new task description, search the codebase for any additional files, classes, functions, and patterns that are relevant to the new task but not already covered.
6. Read all newly relevant files thoroughly. 6. Read all newly relevant files thoroughly.
Write TWO files: Write two files.
### File 1: .ai/<PROJECT>/about.md (REWRITE) File 1: .ai/<PROJECT>/about.md (rewrite)
NOTE: This file is NOT used by any agent in the current task. It exists solely as a starting point for a FUTURE follow-up task's context gatherer. No planning, implementation, or review agent will ever read it. You are rewriting it now so that the next follow-up has an accurate project overview to start from. Rewrite this file instead of appending to it. The new about.md must be a single coherent document that describes the project as if everything, including this new task's changes, is already fully implemented and working.
REWRITE this file (not append). The new about.md must be a single coherent document that describes the project as if everything — including this new task's changes — is already fully implemented and working.
It should incorporate: It should incorporate:
- Everything from the old about.md that is still accurate and relevant - everything from the old about.md that is still accurate and relevant
- The new task's functionality described as part of the project (not as "changes to make") - the new task's functionality described as part of the project, not as a pending change
- Any changed design decisions or architectural updates from the new task requirements - any changed design decisions or architectural updates from the new task requirements
It should NOT contain: It should not contain:
- Any temporal state: "Current State", "Pending Changes", "TODO", "Not yet implemented" - temporal state such as "Current State", "Pending Changes", or "TODO"
- History of how requirements changed between tasks - history of how requirements changed between tasks
- References to "the old approach" vs "the new approach" - references to "the old approach" versus "the new approach"
- Task-by-task changelog or timeline - task-by-task changelog or timeline
- Any distinction between "what was done before" and "what this task adds" - information that contradicts the new task requirements
- Information that contradicts the new task requirements (if the new task changes direction, the about.md should reflect the NEW direction as if it was always the plan)
### File 2: .ai/<PROJECT>/<LETTER>/context.md File 2: .ai/<PROJECT>/<LETTER>/context.md
This is the PRIMARY document — all downstream agents (planning, implementation, review) will read ONLY this file. It must be completely self-contained. about.md will NOT be available to them. This is the primary document for the new task. It must be self-contained and should include:
- Task Description: The new task restated clearly, with enough project background that an implementation agent can understand it without reading any other .ai files
- Relevant Files: Every file path with line ranges relevant to this task
- Key Code Patterns: How similar things are done in the codebase
- Data Structures: Relevant types, structs, classes
- API Methods: Any TL schema methods involved
- UI Styles: Any relevant style definitions
- Localization: Any relevant string keys
- Build Info: Build command and any special notes
- Reference Implementations: Similar features that can serve as templates
It should contain: Be extremely thorough. Another agent with no prior context should be able to work from this file alone.
- **Task Description**: The new task restated clearly, with enough project background (from about.md and previous context.md) that an implementation agent can understand it without reading any other .ai/ files
- **Relevant Files**: Every file path with line ranges relevant to THIS task (including files modified by previous tasks and any newly relevant files)
- **Key Code Patterns**: How similar things are done in the codebase
- **Data Structures**: Relevant types, structs, classes
- **API Methods**: Any TL schema methods involved
- **UI Styles**: Any relevant style definitions
- **Localization**: Any relevant string keys
- **Build Info**: Build command and any special notes
- **Reference Implementations**: Similar features that can serve as templates
Be extremely thorough. Another agent with NO prior context will read ONLY this file and must be able to understand everything needed to implement the new task. Do NOT assume the reader has seen about.md or any previous task files. The context.md is the single source of truth for all downstream agents — it must include all relevant project background, not just the delta.
Do not implement code in this phase. Do not implement code in this phase.
``` ```
@@ -150,7 +156,7 @@ Do not implement code in this phase.
You are a planning agent. You must create a detailed implementation plan. You are a planning agent. You must create a detailed implementation plan.
Read these files: Read these files:
- .ai/<PROJECT>/<LETTER>/context.md - Contains all gathered context for this task - .ai/<PROJECT>/<LETTER>/context.md
- Then read the specific source files referenced in context.md to understand the code deeply. - Then read the specific source files referenced in context.md to understand the code deeply.
Create a detailed plan in: .ai/<PROJECT>/<LETTER>/plan.md Create a detailed plan in: .ai/<PROJECT>/<LETTER>/plan.md
@@ -172,24 +178,23 @@ The plan.md should contain:
## Implementation Steps ## Implementation Steps
Each step must be specific enough that an agent can execute it without ambiguity: Each step must be specific enough that an agent can execute it without ambiguity:
- Exact file paths - exact file paths
- Exact function names - exact function names
- What code to add/modify/remove - what code to add, modify, or remove
- Where exactly in the file (after which function, in which class, etc.) - where exactly in the file (after which function, in which class, and so on)
Number every step. Group steps into phases if there are more than ~8 steps. Number every step. Group steps into phases if there are more than about eight steps.
### Phase 1: <name> ### Phase 1: <name>
1. <specific step> 1. <specific step>
2. <specific step> 2. <specific step>
...
### Phase 2: <name> (if needed) ### Phase 2: <name> (if needed)
... 1. <specific step>
## Build Verification ## Build Verification
- Build command to run - build command to run
- Expected outcome - expected outcome
## Status ## Status
- [ ] Phase 1: <name> - [ ] Phase 1: <name>
@@ -212,59 +217,68 @@ Read these files:
Assess the plan: Assess the plan:
1. **Correctness**: Are the file paths and line references accurate? Does the plan reference real functions and types? 1. Correctness: Are the file paths and line references accurate? Does the plan reference real functions and types?
2. **Completeness**: Are there missing steps? Edge cases not handled? 2. Completeness: Are there missing steps? Edge cases not handled?
3. **Code quality**: Will the plan minimize code duplication? Does it follow existing codebase patterns from AGENTS.md? 3. Code quality: Will the plan minimize code duplication? Does it follow existing codebase patterns from AGENTS.md?
4. **Design**: Could the approach be improved? Are there better patterns already used in the codebase? 4. Design: Could the approach be improved? Are there better patterns already used in the codebase?
5. **Phase sizing**: Each phase should be implementable by a single agent in one session. If a phase has more than ~8-10 substantive code changes, split it further. 5. Phase sizing: Each phase should be implementable by a single agent in one session. If a phase has more than about 8-10 substantive code changes, split it further.
Update plan.md with your refinements. Keep the same structure but: Update plan.md with your refinements. Keep the same structure but:
- Fix any inaccuracies - fix any inaccuracies
- Add missing steps - add missing steps
- Improve the approach if you found better patterns - improve the approach if you found better patterns
- Ensure phases are properly sized for single-agent execution - ensure phases are properly sized for single-agent execution
- Add a line at the top of the Status section: `Phases: <N>` indicating how many implementation phases there are - add a line at the top of the Status section: `Phases: <N>`
- Add `Assessed: yes` at the bottom of the file - add `Assessed: yes` at the bottom of the file
If the plan is small enough for a single agent (roughly <=8 steps), mark it as a single phase. If the plan is small enough for a single agent (roughly 8 steps or fewer), mark it as a single phase.
Do not implement code in this phase. Do not implement code in this phase.
``` ```
## Phase 4: Implementation ## Phase 4: Implementation
For each phase in the plan that is not yet marked as done, run a separate child session: Run one implementation unit per plan phase. Keep implementation phases sequential by default. Parallelize only if their write sets are disjoint and the plan makes that safe.
For each phase in the plan that is not yet marked as done, use this prompt:
```text ```text
You are an implementation agent working on phase <N> of an implementation plan. You are an implementation agent working on phase <N> of an implementation plan.
Read these files first: Read these files first:
- .ai/<PROJECT>/<LETTER>/context.md - Full codebase context - .ai/<PROJECT>/<LETTER>/context.md
- .ai/<PROJECT>/<LETTER>/plan.md - Implementation plan - .ai/<PROJECT>/<LETTER>/plan.md
Then read the source files you'll be modifying. Then read the source files you will be modifying.
YOUR TASK: Implement ONLY Phase <N> from the plan: Your owned write set for this phase:
<OWNED_WRITE_SET>
YOUR TASK: Implement only Phase <N> from the plan:
<paste the specific phase steps here> <paste the specific phase steps here>
Rules: Rules:
- Follow the plan precisely - Follow the plan precisely.
- Follow AGENTS.md coding conventions (no comments except complex algorithms, use auto, empty line before closing brace, etc.) - Follow AGENTS.md coding conventions.
- Do NOT modify .ai/ files except to update the Status section in plan.md - You are not alone in the codebase. Respect existing changes and do not revert unrelated work.
- Do not modify .ai/ files except to update the Status section in plan.md.
- When done, update plan.md Status section: change `- [ ] Phase <N>: ...` to `- [x] Phase <N>: ...` - When done, update plan.md Status section: change `- [ ] Phase <N>: ...` to `- [x] Phase <N>: ...`
- Do NOT work on other phases - Do not work on other phases.
When finished, report what you did and any issues encountered. When finished, report what you did, which files you changed, and any issues encountered.
``` ```
After each implementation agent returns: After each implementation phase:
1. Read `plan.md` to check the status was updated. 1. Read `plan.md` to confirm the status was updated.
2. If more phases remain, run the next implementation child session. 2. Verify the owned write set and touched files make sense.
3. If all phases are done, proceed to build verification. 3. If more phases remain, run the next implementation phase.
4. If all phases are done, proceed to build verification.
## Phase 5: Build Verification ## Phase 5: Build Verification
Only run this phase if the task involved modifying project source code (not just docs or config). Only run this phase if the task modified project source code.
Prefer running the build in the main session because it is critical-path work. If you delegate it, use a worker subagent and wait immediately for the result.
```text ```text
You are a build verification agent. You are a build verification agent.
@@ -273,7 +287,7 @@ Read these files:
- .ai/<PROJECT>/<LETTER>/context.md - .ai/<PROJECT>/<LETTER>/context.md
- .ai/<PROJECT>/<LETTER>/plan.md - .ai/<PROJECT>/<LETTER>/plan.md
The implementation is complete. Your job is to build the project and fix any build errors. The implementation is complete. Your job is to build the project and fix any build errors that block the planned work.
Steps: Steps:
1. Run (from repository root): cmake --build ./out --config Debug --target Telegram 1. Run (from repository root): cmake --build ./out --config Debug --target Telegram
@@ -286,76 +300,66 @@ Steps:
e. Update plan.md status when done e. Update plan.md status when done
Rules: Rules:
- Only fix build errors, do not refactor or improve code - Only fix build errors. Do not refactor or improve code beyond what is needed for a passing build.
- Follow AGENTS.md conventions - Follow AGENTS.md conventions.
- If build fails with file-locked errors (C1041, LNK1104), STOP and report - do not retry - If build fails with file-locked errors (C1041, LNK1104, "cannot open output file", or similar access-denied lock issues), stop and report the lock. Do not retry.
- You are not alone in the codebase. Respect existing changes and do not revert unrelated work.
When finished, report the build result. When finished, report the build result and which files, if any, you changed.
``` ```
## Phase 6: Code Review Loop ## Phase 6: Code Review Loop
After build verification passes, run up to 3 review-fix iterations to improve code quality. Set iteration counter `R = 1`. After build verification passes, run up to 3 review-fix iterations. Set iteration counter `R = 1`.
### Review Loop Review loop:
``` ```text
LOOP: LOOP:
1. Run review agent (Step 6a) with iteration R 1. Run review phase 6a with iteration R.
2. Read review<R>.md verdict: 2. Read review<R>.md verdict:
- "APPROVED" → go to FINISH - "APPROVED" -> go to FINISH
- Has improvement suggestions → run fix agent (Step 6b) - "NEEDS_CHANGES" -> run fix phase 6b
3. After fix agent completes and build passes: 3. After fix work completes and build passes:
R = R + 1 R = R + 1
If R > 3 → go to FINISH (stop iterating, accept current state) If R > 3 -> go to FINISH
Otherwise → go to step 1 Otherwise -> go to step 1
FINISH: FINISH:
- Update plan.md: change `- [ ] Code review` to `- [x] Code review` - Update plan.md: change `- [ ] Code review` to `- [x] Code review`
- Proceed to Completion - Proceed to Completion
``` ```
### Step 6a: Code Review Agent ### Step 6a: Code Review
```text ```text
You are a code review agent for Telegram Desktop (C++ / Qt). You are a code review agent for Telegram Desktop (C++ / Qt).
Read these files: Read these files:
- .ai/<PROJECT>/<LETTER>/context.md - Codebase context - .ai/<PROJECT>/<LETTER>/context.md
- .ai/<PROJECT>/<LETTER>/plan.md - Implementation plan - .ai/<PROJECT>/<LETTER>/plan.md
- REVIEW.md - Style and formatting rules to enforce - REVIEW.md
<if R > 1, also read:> - If R > 1, also read .ai/<PROJECT>/<LETTER>/review<R-1>.md
- .ai/<PROJECT>/<LETTER>/review<R-1>.md - Previous review (to see what was already addressed)
Then run `git diff` to see all uncommitted changes made by the implementation. Implementation agents do not commit, so `git diff` shows exactly the current feature's changes. Then run `git diff` to see the current uncommitted changes for this task.
Then read the modified source files in full to understand changes in context. Read the modified source files in full to understand the changes in context.
Perform a thorough code review. Perform a focused code review using these criteria, in order:
REVIEW CRITERIA (in order of importance): 1. Correctness and safety: Obvious logic errors, missing null checks at API boundaries, potential crashes, use-after-free, dangling references, race conditions.
2. Dead code: Added or left-behind code that is never used within the scope of the changes.
3. Redundant changes: Diff hunks that have no functional effect.
4. Code duplication: Repeated logic that should be shared.
5. Wrong placement: Code added to a module where it does not logically belong.
6. Function decomposition: Whether an extracted helper would clearly improve readability.
7. Module structure: Only in exceptional cases where a large new chunk of code clearly belongs elsewhere.
8. Style compliance: REVIEW.md rules and AGENTS.md conventions.
1. **Correctness and safety**: Obvious logic errors, missing null checks at API boundaries, potential crashes, use-after-free, dangling references, race conditions. This is the highest priority — bugs and safety issues must be caught first. Do NOT nitpick internal code that relies on framework guarantees. Important guidelines:
- Review only the changes made, not pre-existing code outside the scope of the task.
2. **Dead code**: Any code added or left behind that is never called or used, within the scope of the changes. Unused variables, unreachable branches, leftover scaffolding. - Be pragmatic. Each suggestion should have a clear, concrete benefit.
- Do not suggest comments, docstrings, or over-engineering.
3. **Redundant changes**: Changes in the diff that have no functional effect — moving declarations or code blocks to a different location without reason, reformatting untouched code, reordering includes or fields with no purpose. Every line in the diff should serve the feature. If a file appears in `git diff` but contains only no-op rearrangements, flag it for revert.
4. **Code duplication**: Unnecessary repetition of logic that should be shared. Look for near-identical blocks that differ only in minor details and could be unified.
5. **Wrong placement**: Code added to a module where it doesn't logically belong. If another existing module is a clearly better fit for the new code, flag it. Consider the existing module boundaries and responsibilities visible in context.md.
6. **Function decomposition**: For longer functions (roughly 50+ lines), consider whether a logical sub-task could be cleanly extracted into a separate function. This is NOT a hard rule — a 100-line function that flows naturally and isn't easily divisible is perfectly fine. But sometimes even a 20-line function contains a clear isolated subtask that reads better as two 10-line functions. The key is to think about it each time: does extracting improve readability and reduce cognitive load, or does it just scatter logic across call sites for no real benefit? Only suggest extraction when there's a genuinely self-contained piece of logic with a clear name and purpose.
7. **Module structure**: Only in exceptional cases — if a large amount of newly added code (hundreds of lines) is logically distinct from the rest of its host module, suggest extracting it into a new module. But do NOT suggest new modules lightly: every module adds significant build overhead due to PCH and heavy template usage. Only suggest this when the new code is both large enough AND logically separated enough to justify it. At the same time, don't let modules grow into multi-thousand-line monoliths either.
8. **Style compliance**: Verify adherence to REVIEW.md rules (empty line before closing brace, operators at start of continuation lines, minimize type checks with direct cast instead of is+as, no if-with-initializer when simpler alternatives exist) and AGENTS.md conventions (no unnecessary comments, `auto` usage, no hardcoded sizes — must use .style definitions), etc.
IMPORTANT GUIDELINES:
- Review ONLY the changes made, not pre-existing code in the repository.
- Be pragmatic. Don't suggest changes for the sake of it. Each suggestion should have a clear, concrete benefit.
- Don't suggest adding comments, docstrings, or type annotations — the codebase style avoids these.
- Don't suggest error handling for impossible scenarios or over-engineering.
Write your review to: .ai/<PROJECT>/<LETTER>/review<R>.md Write your review to: .ai/<PROJECT>/<LETTER>/review<R>.md
@@ -368,113 +372,87 @@ The review document should contain:
## Verdict: <APPROVED or NEEDS_CHANGES> ## Verdict: <APPROVED or NEEDS_CHANGES>
<If APPROVED, stop here. Everything looks good.> If the verdict is NEEDS_CHANGES, continue with:
<If NEEDS_CHANGES, continue with:>
## Changes Required ## Changes Required
### <Issue 1 title> ### <Issue 1 title>
- **Category**: <dead code | duplication | wrong placement | function decomposition | module structure | style | correctness> - Category: <dead code | duplication | wrong placement | function decomposition | module structure | style | correctness>
- **File(s)**: <file paths> - File(s): <file paths>
- **Problem**: <clear description of what's wrong> - Problem: <clear description>
- **Fix**: <specific description of what to change> - Fix: <specific description of what to change>
### <Issue 2 title> Keep the list focused. Prioritize the most impactful issues.
...
Keep the list focused. Only include issues that genuinely improve the code. If you find yourself listing more than ~5-6 issues, prioritize the most impactful ones.
When finished, report your verdict clearly as: APPROVED or NEEDS_CHANGES. When finished, report your verdict clearly as: APPROVED or NEEDS_CHANGES.
``` ```
### Step 6b: Review Fix Agent ### Step 6b: Review Fix
```text ```text
You are a review fix agent. You implement improvements identified during code review. You are a review fix agent. You implement improvements identified during code review.
Read these files: Read these files:
- .ai/<PROJECT>/<LETTER>/context.md - Codebase context - .ai/<PROJECT>/<LETTER>/context.md
- .ai/<PROJECT>/<LETTER>/plan.md - Original implementation plan - .ai/<PROJECT>/<LETTER>/plan.md
- .ai/<PROJECT>/<LETTER>/review<R>.md - Code review with required changes - .ai/<PROJECT>/<LETTER>/review<R>.md
Then read the source files mentioned in the review. Then read the source files mentioned in the review.
YOUR TASK: Implement ALL changes listed in review<R>.md. YOUR TASK: Implement all changes listed in review<R>.md.
For each issue in the review: Rules:
1. Read the relevant source file(s). - Implement exactly the review changes, nothing more.
2. Make the specified change. - Follow AGENTS.md coding conventions.
3. Verify the change makes sense in context. - You are not alone in the codebase. Respect existing changes and do not revert unrelated work.
- Do not modify .ai/ files except where the review process explicitly requires it.
After all changes are made: After all changes are made:
1. Build (from repository root): cmake --build ./out --config Debug --target Telegram 1. Build (from repository root): cmake --build ./out --config Debug --target Telegram
2. If the build fails, fix build errors and rebuild until it passes. 2. If the build fails, fix build errors and rebuild until it passes.
3. If build fails with file-locked errors (C1041, LNK1104), STOP and report - do not retry. 3. If build fails with file-locked errors (C1041, LNK1104, "cannot open output file", or similar access-denied lock issues), stop and report the lock. Do not retry.
Rules: When finished, report what changes were made and which files you touched.
- Implement exactly the changes from the review, nothing more.
- Follow AGENTS.md coding conventions.
- Do NOT modify .ai/ files.
When finished, report what changes were made.
``` ```
## Completion ## Completion
When all phases including build verification and code review are done: When all phases, including build verification and code review, are done:
1. Read the final `plan.md` and report the summary to the user. 1. Read the final `plan.md` and report the summary to the user.
2. Show which files were modified/created. 2. Show which files were modified or created.
3. Note any issues encountered during implementation. 3. Note any issues encountered during implementation.
4. Summarize code review iterations: how many rounds, what was found and fixed, or if it was approved on first pass. 4. Summarize the code review iterations: how many rounds, what was found and fixed, or whether it was approved on the first pass.
5. Calculate and display the total elapsed time since `$START_TIME` (format as `Xh Ym Zs`, omitting zero components — e.g. `12m 34s` or `1h 5m 12s`). 5. Calculate and display the total elapsed time since `$START_TIME` (format as `Xh Ym Zs`, omitting zero components).
6. Remind the user of the project name so they can request follow-up tasks within the same project. 6. Remind the user of the project name so they can request follow-up tasks within the same project.
## Error Handling ## Error Handling
- If any phase fails or gets stuck, report the issue to the user and ask how to proceed. - If any phase fails or gets stuck, report the issue to the user and ask how to proceed.
- If context.md or plan.md is not written properly by a phase, re-run that phase with more specific instructions. - If `context.md` or `plan.md` is not written properly by a phase, rerun that phase with more specific instructions.
- If build errors persist after the build phase's attempts, report the remaining errors to the user. - If build errors persist after the build phase's attempts, report the remaining errors to the user.
- If a review fix phase introduces new build errors that it cannot resolve, report to the user. - If a review-fix phase introduces new build errors that it cannot resolve, report to the user.
## Model And Reasoning ## Prompt Delivery And Logs
All child sessions must use: For each phase:
- `--model gpt-5.4` 1. Write the full prompt to `.ai/<PROJECT>/<LETTER>/logs/phase-<name>.prompt.md`
- `-c model_reasoning_effort="xhigh"` 2. Delegate by sending that prompt text to a fresh subagent, or use it as a same-session checklist
3. Save a concise completion note to `.ai/<PROJECT>/<LETTER>/logs/phase-<name>.result.md`
Use the same settings for every phase, including setup, implementation, build verification, and review-fix runs. For review iterations, include the iteration in the file name, for example:
- `phase-6a-review-1.prompt.md`
- `phase-6a-review-1.result.md`
- `phase-6b-fix-1.prompt.md`
- `phase-6b-fix-1.result.md`
## Prompt Delivery ## Subagent Pattern
Phase prompts can be large and contain complex formatting. Do not inline them as a quoted CLI argument. For each phase: Use this pattern conceptually for delegated phases:
1. Write the full prompt to a file in `.ai/<PROJECT>/<LETTER>/logs/phase-<name>.prompt.md`
2. Pipe the file contents into `codex exec` with `Get-Content -Raw <prompt-file> | codex exec ... -`
3. Save the JSONL stream to the matching `phase-<name>.jsonl`
If a sandboxed child launch fails with `Access is denied` in Codex desktop, retry the same command through an escalated shell invocation before falling back to same-session execution. 1. Write the phase prompt file.
2. Spawn a fresh subagent with the phase prompt, usually with `fork_context: false`.
3. Wait when the next step is blocked on that phase.
4. Validate the expected artifact or code changes.
5. Write the result log.
## Example Runner Commands Do not replace this pattern with shell-launched `codex exec`.
```powershell
$PromptFile = ".ai/<PROJECT>/<LETTER>/logs/phase-1-context.prompt.md"
Get-Content -Raw $PromptFile | codex exec --json --full-auto --model gpt-5.4 -c model_reasoning_effort="xhigh" -C <REPO_ROOT> - | Tee-Object .ai/<PROJECT>/<LETTER>/logs/phase-1-context.jsonl
$PromptFile = ".ai/<PROJECT>/<LETTER>/logs/phase-2-plan.prompt.md"
Get-Content -Raw $PromptFile | codex exec --json --full-auto --model gpt-5.4 -c model_reasoning_effort="xhigh" -C <REPO_ROOT> - | Tee-Object .ai/<PROJECT>/<LETTER>/logs/phase-2-plan.jsonl
$PromptFile = ".ai/<PROJECT>/<LETTER>/logs/phase-3-assess.prompt.md"
Get-Content -Raw $PromptFile | codex exec --json --full-auto --model gpt-5.4 -c model_reasoning_effort="xhigh" -C <REPO_ROOT> - | Tee-Object .ai/<PROJECT>/<LETTER>/logs/phase-3-assess.jsonl
$PromptFile = ".ai/<PROJECT>/<LETTER>/logs/phase-4-impl-N.prompt.md"
Get-Content -Raw $PromptFile | codex exec --json --full-auto --model gpt-5.4 -c model_reasoning_effort="xhigh" -C <REPO_ROOT> - | Tee-Object .ai/<PROJECT>/<LETTER>/logs/phase-4-impl-N.jsonl
$PromptFile = ".ai/<PROJECT>/<LETTER>/logs/phase-5-build.prompt.md"
Get-Content -Raw $PromptFile | codex exec --json --full-auto --model gpt-5.4 -c model_reasoning_effort="xhigh" -C <REPO_ROOT> - | Tee-Object .ai/<PROJECT>/<LETTER>/logs/phase-5-build.jsonl
$PromptFile = ".ai/<PROJECT>/<LETTER>/logs/phase-6a-review-R.prompt.md"
Get-Content -Raw $PromptFile | codex exec --json --full-auto --model gpt-5.4 -c model_reasoning_effort="xhigh" -C <REPO_ROOT> - | Tee-Object .ai/<PROJECT>/<LETTER>/logs/phase-6a-review-R.jsonl
$PromptFile = ".ai/<PROJECT>/<LETTER>/logs/phase-6b-fix-R.prompt.md"
Get-Content -Raw $PromptFile | codex exec --json --full-auto --model gpt-5.4 -c model_reasoning_effort="xhigh" -C <REPO_ROOT> - | Tee-Object .ai/<PROJECT>/<LETTER>/logs/phase-6b-fix-R.jsonl
```
.agents/skills/task-think/SKILL.md
+39 -40
View File
@@ -1,6 +1,6 @@
--- ---
name: task-think name: task-think
description: Orchestrate a multi-phase implementation workflow for this repository with artifact files under .ai/<project-name>/<letter>/ and fresh codex exec child runs per phase. Use when the user wants one prompt to drive context gathering, planning, plan assessment, implementation, build verification, and review iterations while keeping the main session context clean. description: Orchestrate a multi-phase implementation workflow for this repository with artifact files under .ai/<project-name>/<letter>/ using Codex subagents instead of shell-spawned child processes. Use when the user wants one prompt to drive context gathering, planning, plan assessment, implementation, build verification, and review with persistent artifacts and clear phase handoffs. Prefer spawn_agent/send_input/wait_agent; fall back to same-session execution only when delegation is unavailable or disallowed.
--- ---
# Task Pipeline # Task Pipeline
@@ -15,14 +15,14 @@ Collect:
- optional constraints (files, architecture, risk tolerance) - optional constraints (files, architecture, risk tolerance)
- optional screenshot paths - optional screenshot paths
If screenshots are attached in UI but not present as files, write a brief textual summary in `.ai/<project-name>/about.md` so child runs can consume the requirements. If screenshots are attached in UI but not present as files, write a brief textual summary into the task artifacts before spawning fresh subagents so later phases can read the requirements without inheriting the whole parent thread.
## Overview ## Overview
The workflow is organized around **projects**. Each project lives in `.ai/<project-name>/` and can contain multiple sequential **tasks** (labeled `a`, `b`, `c`, ... `z`). The workflow is organized around projects. Each project lives in `.ai/<project-name>/` and can contain multiple sequential tasks (labeled `a`, `b`, `c`, ... `z`).
Project structure: Project structure:
``` ```text
.ai/<project-name>/ .ai/<project-name>/
about.md # Single source of truth for the entire project about.md # Single source of truth for the entire project
a/ # First task a/ # First task
@@ -31,16 +31,21 @@ Project structure:
review1.md # Code review documents (up to 3 iterations) review1.md # Code review documents (up to 3 iterations)
review2.md review2.md
review3.md review3.md
logs/
phase-*.prompt.md
phase-*.result.md
b/ # Follow-up task b/ # Follow-up task
context.md context.md
plan.md plan.md
review1.md review1.md
logs/
...
c/ # Another follow-up task c/ # Another follow-up task
... ...
``` ```
- `about.md` is the project-level blueprint — a single comprehensive document describing what this project does and how it works, written as if everything is already fully implemented. It contains no temporal state ("current state", "pending changes", "not yet implemented"). It is **rewritten** (not appended to) each time a new task starts, incorporating the new task's changes as if they were always part of the design. - `about.md` is the project-level blueprint: a single comprehensive document describing what this project does and how it works, written as if everything is already fully implemented. It contains no temporal state ("current state", "pending changes", "not yet implemented"). It is rewritten, not appended to, each time a new task starts, incorporating the new task's changes as if they were always part of the design.
- Each task folder (`a/`, `b/`, ...) contains self-contained files for that task. The task's `context.md` carries all task-specific information: what specifically needs to change, the delta from the current codebase, gathered file references and code patterns. Planning, implementation, and review agents only read the current task's folder. - Each task folder (`a/`, `b/`, ...) contains self-contained files for that task. The task's `context.md` carries all task-specific information: what specifically needs to change, the delta from the current codebase, gathered file references, and code patterns. Planning, implementation, and review phases should rely on the current task folder.
## Artifacts ## Artifacts
@@ -49,44 +54,38 @@ Create and maintain:
- `.ai/<project-name>/<letter>/context.md` - `.ai/<project-name>/<letter>/context.md`
- `.ai/<project-name>/<letter>/plan.md` - `.ai/<project-name>/<letter>/plan.md`
- `.ai/<project-name>/<letter>/review<R>.md` (up to 3 review iterations) - `.ai/<project-name>/<letter>/review<R>.md` (up to 3 review iterations)
- `.ai/<project-name>/<letter>/logs/phase-*.jsonl` (when running child `codex exec`) - `.ai/<project-name>/<letter>/logs/phase-<name>.prompt.md`
- `.ai/<project-name>/<letter>/logs/phase-<name>.result.md`
Each `phase-<name>.result.md` should capture a concise outcome summary: whether the phase completed, which files it touched, and any follow-up notes or blockers.
## Phases ## Phases
The workflow runs these phases sequentially via `codex exec --json` child sessions: Run these phases sequentially:
1. **Phase 0: Setup** — Record start time, detect follow-up vs new project, create directories. 1. Phase 0: Setup - Record start time, detect follow-up vs new project, create directories.
2. **Phase 1: Context Gathering** — Read codebase, write `about.md` and `context.md`. (Phase 1F for follow-ups.) 2. Phase 1: Context Gathering - Read codebase, write `about.md` and `context.md`. Use Phase 1F for follow-up tasks.
3. **Phase 2: Planning** — Read context, write detailed `plan.md` with numbered steps grouped into phases. 3. Phase 2: Planning - Read context, write detailed `plan.md` with numbered steps grouped into phases.
4. **Phase 3: Plan Assessment** — Review and refine the plan for correctness, completeness, code quality, and phase sizing. 4. Phase 3: Plan Assessment - Review and refine the plan for correctness, completeness, code quality, and phase sizing.
5. **Phase 4: Implementation** — One child session per plan phase. Each implements only its assigned phase and updates `plan.md` status. 5. Phase 4: Implementation - Execute one implementation unit per plan phase.
6. **Phase 5: Build Verification** — Build the project, fix any build errors. Skip if no source code was modified. 6. Phase 5: Build Verification - Build the project, fix any build errors. Skip if no source code was modified.
7. **Phase 6: Code Review Loop** — Up to 3 review-fix iterations: 7. Phase 6: Code Review Loop - Run review and fix iterations until approved or the iteration limit is reached.
- 6a: Review agent writes `review<R>.md` with verdict (APPROVED or NEEDS_CHANGES).
- 6b: Fix agent implements review changes and rebuilds.
- Loop until APPROVED or R > 3.
Use the phase prompt templates in `PROMPTS.md`. Use the phase prompt templates in `PROMPTS.md`.
## Execution Mode ## Execution Mode
Run `codex exec --json` child sessions for each phase. Wait for each to finish before starting the next. After each phase, validate that the expected artifact file exists and has substantive content. Use Codex subagents as the primary orchestration mechanism.
Every child session must use: - Spawn a fresh subagent for context gathering, planning, plan assessment, each implementation phase, and each review or review-fix pass when delegation is available.
- `--model gpt-5.4` - Prefer `worker` for phases that write files. Use `explorer` only for narrow read-only questions that unblock your next local step.
- `-c model_reasoning_effort="xhigh"` - Keep `fork_context` off by default. Pass the phase prompt and explicit file paths instead of the whole thread unless the phase truly needs prior conversational context or thread-only attachments.
- When the platform supports it, request `model: gpt-5.4` and `reasoning_effort: xhigh` for spawned phase agents. If overrides are unavailable, inherit the current session settings.
Do not pass long or complex phase prompts as a quoted command-line argument. Instead: - Write the exact phase prompt to the matching `logs/phase-<name>.prompt.md` file before you delegate. Use the same prompt file as a checklist if you later need to fall back to same-session execution.
- Write the full phase prompt to a per-phase prompt file under `.ai/<project-name>/<letter>/logs/` - After a subagent finishes, verify that the expected artifacts or code changes exist, then write a short result log in `logs/phase-<name>.result.md`.
- Pipe that file into `codex exec` with `Get-Content -Raw <prompt-file> | codex exec ... -` - Use `wait_agent` only when the next step is blocked on the result. While the delegated phase runs, do small non-overlapping local tasks such as validating directory structure or preparing the next prompt file.
- Save the JSONL transcript to the matching `phase-*.jsonl` log file - Build verification is critical-path work. Prefer running the build in the main session, and only delegate a bounded build-fix phase when there is a concrete reason.
- If subagents are unavailable in the current environment, or current policy does not allow delegation for this request, run the phase in the main session using the same prompt files. Never fall back to shell-spawned `codex exec` child processes from this skill.
When running inside Codex desktop on Windows, a child `codex exec` may fail inside the normal agent sandbox with `Access is denied` even though the command itself is valid. If that happens:
- Re-run the same `codex exec` invocation through an escalated shell tool call
- Do not treat the first sandboxed launch failure as a phase failure
- Fall back to direct main-session execution only if escalated child execution is unavailable or denied
Use the phase prompt templates and runner patterns in `PROMPTS.md`.
## Verification Rules ## Verification Rules
@@ -107,19 +106,19 @@ Mark complete only when:
## Error Handling ## Error Handling
- If any phase fails or gets stuck, report the issue to the user and ask how to proceed. - If any phase fails, times out, or gets stuck, inspect the partial artifacts, tighten the prompt, and retry with a fresh subagent or same-session fallback. Report the issue to the user if you remain blocked.
- If context.md or plan.md is not written properly by a phase, re-run that phase with more specific instructions. - If `context.md` or `plan.md` is not written properly by a phase, rerun that phase with more specific instructions.
- If build errors persist after the build phase's attempts, report the remaining errors to the user. - If build errors persist after the build phase's attempts, report the remaining errors to the user.
- If a review fix phase introduces new build errors that it cannot resolve, report to the user. - If a review-fix phase introduces new build errors that it cannot resolve, report to the user.
## User Invocation ## User Invocation
Use plain language with the skill name in the request, for example: Use plain language with the skill name in the request, for example:
`Use local task-think skill: make sure FileLoadTask::process does not create or read QPixmap on background threads; use QImage with ARGB32_Premultiplied instead.` `Use local task-think skill with subagents: make sure FileLoadTask::process does not create or read QPixmap on background threads; use QImage with ARGB32_Premultiplied instead.`
For follow-up tasks on an existing project: For follow-up tasks on an existing project:
`Use local task-think skill: my-project also handle the case where the file is already cached` `Use local task-think skill with subagents: my-project also handle the case where the file is already cached`
If screenshots are relevant, include file paths in the same prompt. If screenshots are relevant, include file paths in the same prompt when possible.