diff --git a/.claude/commands/task.md b/.claude/commands/task.md index e682f3de18..6d4b147f45 100644 --- a/.claude/commands/task.md +++ b/.claude/commands/task.md @@ -13,93 +13,66 @@ If `$ARGUMENTS` is provided, it's the task description. If empty, ask the user w ## Overview -The workflow produces `.ai//` containing: -- `context.md` - Gathered codebase context relevant to the task -- `plan.md` - Detailed implementation plan with phases -- `review1.md`, `review2.md`, `review3.md` - Code review documents (up to 3 iterations) +The workflow is organized around **projects**. Each project lives in `.ai//` and can contain multiple sequential **tasks** (labeled `a`, `b`, `c`, ... `z`). -Then spawns implementation agents to execute each phase, verifies the build, and runs up to 3 review-fix iterations to improve code quality. +Project structure: +``` +.ai// + about.md # Single source of truth for the entire project + a/ # First task + context.md # Gathered codebase context for this task + plan.md # Implementation plan + review1.md # Code review documents (up to 3) + review2.md + review3.md + b/ # Follow-up task + context.md + plan.md + review1.md + 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. +- 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. ## Phase 0: Setup -1. Understand the task from `$ARGUMENTS` or ask the user. -2. **Follow-up detection:** Check if `$ARGUMENTS` starts with a task name (the first word/token before any whitespace or newline). Look for `.ai//` directory: - - If `.ai//` exists AND contains both `context.md` and `plan.md`, this is a **follow-up task**. Read both files. The rest of `$ARGUMENTS` (after the task name) is the follow-up task description describing what additional changes are needed. - - If no matching directory exists, this is a **new task** - proceed normally. -3. For new tasks: check existing folders in `.ai/` to pick a unique short name (1-2 lowercase words, hyphen-separated) and create `.ai//`. -4. For follow-up tasks: the folder already exists, skip creation. +⚠️ **CRITICAL: Follow-up detection MUST happen FIRST, before anything else.** -### Follow-up Task Flow +### Step 0a: Follow-up detection (MANDATORY — do this BEFORE understanding the task) -When a follow-up task is detected (existing `.ai//` with `context.md` and `plan.md`): +Extract the first word/token from `$ARGUMENTS` (everything before the first space or newline). Call it `FIRST_TOKEN`. -1. Skip Phase 1 (Context Gathering) - context already exists. -2. Skip Phase 2 (Planning) - original plan already exists. -3. Go directly to **Phase 2F (Follow-up Planning)** instead of Phase 3. +Then run these TWO commands using the Bash tool, IN PARALLEL, right now: +1. `ls .ai/` — to see all existing project names +2. `ls .ai//about.md` — to check if this specific project exists -**Phase 2F: Follow-up Planning** +**Evaluate the results:** +- If command 2 **succeeds** (the file exists): this is a **follow-up task**. The project name is `FIRST_TOKEN`. The task description is everything in `$ARGUMENTS` AFTER `FIRST_TOKEN` (strip leading whitespace). +- If command 2 **fails** (file not found): this is a **new project**. The full `$ARGUMENTS` is the task description. -Spawn an agent (Task tool, subagent_type=`general-purpose`) with this prompt: +**Do NOT proceed to step 0b until you have run these commands and determined follow-up vs new.** -``` -You are a planning agent for a follow-up task on an existing implementation. +### Step 0b: Project setup -Read these files: -- .ai//context.md - Previously gathered codebase context -- .ai//plan.md - Previous implementation plan (already completed) +**For new projects:** +- Using the list from command 1, pick a unique short name (1-2 lowercase words, hyphen-separated) that doesn't collide with existing projects. +- Create `.ai//` and `.ai//a/`. +- Set current task letter = `a`. -Then read the source files referenced in context.md and plan.md to understand what was already implemented. +**For follow-up tasks:** +- Scan `.ai//` for existing task folders (`a/`, `b/`, ...). Find the latest one (highest letter). +- The previous task letter = that highest letter. +- The new task letter = next letter in sequence. +- Create `.ai///`. -FOLLOW-UP TASK: - -The previous plan was already implemented and tested. Now there are follow-up changes needed. - -YOUR JOB: -1. Understand what was already done from plan.md (look at the completed phases). -2. Read the actual source files to see the current state of the code. -3. If context.md needs updates for the follow-up task (new files relevant, new patterns needed), update it with additional sections marked "## Follow-up Context (iteration 2)" or similar. -4. Create a NEW follow-up plan. Update plan.md by: - - Keep the existing content as history (do NOT delete it) - - Add a new section at the end: - - --- - ## Follow-up Task - - - ## Follow-up Approach - - - ## Follow-up Files to Modify - - - ## Follow-up Implementation Steps - - ### Phase F1: - 1. - 2. ... - - ### Phase F2: (if needed) - ... - - ## Follow-up Status - Phases: - - [ ] Phase F1: - - [ ] Phase F2: (if applicable) - - [ ] Build verification - - [ ] Code review - Assessed: yes - -Use /ultrathink to reason carefully. The follow-up plan should be self-contained enough that an implementation agent can execute it by reading context.md and the updated plan.md. -``` - -After this agent completes, read `plan.md` to verify the follow-up plan was written. Then proceed to Phase 4 (Implementation), using the follow-up phases (F1, F2, etc.) instead of the original phases. - -### New Task Flow - -When this is a new task (no existing folder), proceed with Phases 1-5 as described below. +Then proceed to Phase 1 (Context Gathering) in both cases. Follow-up tasks do NOT skip context gathering — they go through a modified version of it. ## Phase 1: Context Gathering +### For New Projects (task letter = `a`) + Spawn an agent (Task tool, subagent_type=`general-purpose`) with this prompt structure: ``` @@ -107,7 +80,7 @@ You are a context-gathering agent for a large C++ codebase (Telegram Desktop). TASK: -YOUR JOB: Read CLAUDE.md, inspect the codebase, find ALL files and code relevant to this task, and write a comprehensive context document. +YOUR JOB: Read CLAUDE.md, inspect the codebase, find ALL files and code relevant to this task, and write two documents. Steps: 1. Read CLAUDE.md for project conventions and build instructions. @@ -123,9 +96,23 @@ Steps: 7. Check .style files if the task involves UI. 8. Check lang.strings if the task involves user-visible text. -Write your findings to: .ai//context.md +Write TWO files: -The context.md should contain: +### File 1: .ai//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. + +Write it as if the project is already fully implemented and working. It should contain: +- **Project**: What this project does (feature description, goals, scope) +- **Architecture**: High-level architectural decisions, which modules are involved, how they interact +- **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 + +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. + +### File 2: .ai//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: - **Task Description**: The full task restated clearly - **Relevant Files**: Every file path with line ranges and descriptions of what's there - **Key Code Patterns**: How similar things are done in the codebase (with code snippets) @@ -139,7 +126,69 @@ The context.md should contain: 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. ``` -After this agent completes, read `context.md` to verify it was written properly. +After this agent completes, read both `about.md` and `a/context.md` to verify they were written properly. + +### For Follow-up Tasks (task letter = `b`, `c`, ...) + +Spawn an agent (Task tool, subagent_type=`general-purpose`) with this prompt structure: + +``` +You are a context-gathering agent for a follow-up task on an existing project in a large C++ codebase (Telegram Desktop). + +NEW TASK: + +YOUR JOB: Read the existing project state, gather any additional context needed, and produce fresh documents for the new task. + +Steps: +1. Read CLAUDE.md for project conventions and build instructions. +2. Read .ai//about.md — this is the project-level blueprint describing everything done so far. +3. Read .ai///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. +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. + +Write TWO files: + +### File 1: .ai//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 (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: +- 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") +- Any changed design decisions or architectural updates from the new task requirements + +It should NOT contain: +- Any temporal state: "Current State", "Pending Changes", "TODO", "Not yet implemented" +- History of how requirements changed between tasks +- References to "the old approach" vs "the new approach" +- 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 (if the new task changes direction, the about.md should reflect the NEW direction as if it was always the plan) + +Think of about.md as "the complete description of what this project does and how it works." Someone reading it should understand the full project as a finished product, without knowing it went through multiple tasks. + +### File 2: .ai///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. + +It should contain: +- **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. +``` + +After this agent completes, read both `about.md` and `/context.md` to verify they were written properly. ## Phase 2: Planning @@ -149,12 +198,12 @@ Spawn an agent (Task tool, subagent_type=`general-purpose`) with this prompt str You are a planning agent. You must create a detailed implementation plan. Read these files: -- .ai//context.md - Contains all gathered context +- .ai///context.md - Contains all gathered context for this task - Then read the specific source files referenced in context.md to understand the code deeply. Use /ultrathink to reason carefully about the implementation approach. -Create a detailed plan in: .ai//plan.md +Create a detailed plan in: .ai///plan.md The plan.md should contain: @@ -209,8 +258,8 @@ Spawn an agent (Task tool, subagent_type=`general-purpose`) with this prompt str You are a plan assessment agent. Review and refine an implementation plan. Read these files: -- .ai//context.md -- .ai//plan.md +- .ai///context.md +- .ai///plan.md - Then read the actual source files referenced to verify the plan makes sense. Use /ultrathink to assess the plan: @@ -244,8 +293,8 @@ For each phase in the plan that is not yet marked as done, spawn an implementati You are an implementation agent working on phase of an implementation plan. Read these files first: -- .ai//context.md - Full codebase context -- .ai//plan.md - Implementation plan +- .ai///context.md - Full codebase context +- .ai///plan.md - Implementation plan Then read the source files you'll be modifying. @@ -277,8 +326,8 @@ Spawn a build verification agent (Task tool, subagent_type=`general-purpose`): You are a build verification agent. Read these files: -- .ai//context.md -- .ai//plan.md +- .ai///context.md +- .ai///plan.md The implementation is complete. Your job is to build the project and fix any build errors. @@ -332,11 +381,11 @@ Spawn an agent (Task tool, subagent_type=`general-purpose`): You are a code review agent for Telegram Desktop (C++ / Qt). Read these files: -- .ai//context.md - Codebase context -- .ai//plan.md - Implementation plan +- .ai///context.md - Codebase context +- .ai///plan.md - Implementation plan - REVIEW.md - Style and formatting rules to enforce 1, also read:> -- .ai//review.md - Previous review (to see what was already addressed) +- .ai///review.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. @@ -368,7 +417,7 @@ IMPORTANT GUIDELINES: - 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//review.md +Write your review to: .ai///review.md The review document should contain: @@ -409,9 +458,9 @@ Spawn an agent (Task tool, subagent_type=`general-purpose`): You are a review fix agent. You implement improvements identified during code review. Read these files: -- .ai//context.md - Codebase context -- .ai//plan.md - Original implementation plan -- .ai//review.md - Code review with required changes +- .ai///context.md - Codebase context +- .ai///plan.md - Original implementation plan +- .ai///review.md - Code review with required changes Then read the source files mentioned in the review. @@ -444,6 +493,7 @@ When all phases including build verification and code review are done: 2. Show which files were modified/created. 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. +5. Remind the user of the project name so they can use `/task ` for follow-up changes. ## Error Handling diff --git a/.codex/skills/task-think/PROMPTS.md b/.codex/skills/task-think/PROMPTS.md index f27a9d037b..f86d962849 100644 --- a/.codex/skills/task-think/PROMPTS.md +++ b/.codex/skills/task-think/PROMPTS.md @@ -1,22 +1,123 @@ # Phase Prompts -Use these templates for `codex exec --json` child runs. Replace ``, ``, and ``. +Use these templates for `codex exec --json` child runs. Replace ``, ``, ``, and ``. -## Phase 1: Context +## Phase 0: Setup + +Before running any phase prompts, the orchestrator must determine whether this is a new project or a follow-up task. + +**Follow-up detection:** +1. Extract the first word/token from the task description. Call it `FIRST_TOKEN`. +2. Check if `.ai//about.md` exists. +3. If it exists: this is a **follow-up task**. The project name is `FIRST_TOKEN`. The task description is everything after `FIRST_TOKEN`. +4. If it does not exist: this is a **new project**. The full input is the task description. + +**For new projects:** +- List existing `.ai/` folders to pick a unique short name (1-2 lowercase words, hyphen-separated). +- Create `.ai//` and `.ai//a/` and `logs/`. +- Set `` = `a`. + +**For follow-up tasks:** +- Scan `.ai//` for existing task folders (`a/`, `b/`, ...). Find the latest one (highest letter). +- The new task letter = next letter in sequence. +- Create `.ai///` and `logs/`. + +Then proceed to Phase 1. Follow-up tasks do NOT skip context gathering — they go through a modified version of it. + +## Phase 1: Context (New Project, letter = `a`) ```text You are the context phase for task "" in repository . Read CLAUDE.md for the basic coding rules and guidelines. -Read AGENTS.md and all relevant source files. Write a focused context doc: -- .ai//context.md +Read AGENTS.md and all relevant source files. Write TWO documents: -Include: -1. Relevant files and why they matter -2. Existing patterns to follow -3. Risks and unknowns -4. Verification hooks (what to build/test later) +### File 1: .ai//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. + +Write it as if the project is already fully implemented and working. It should contain: +- **Project**: What this project does (feature description, goals, scope) +- **Architecture**: High-level architectural decisions, which modules are involved, how they interact +- **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 + +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. + +### File 2: .ai//a/context.md + +This is the PRIMARY document — all downstream agents (planning, implementation, review) will read ONLY this file. It must be completely self-contained. Include: +1. Task description restated clearly +2. Relevant files with line ranges and why they matter +3. Existing patterns to follow (with code snippets) +4. Data structures, types, classes +5. API methods (from api.tl if applicable) +6. UI styles (from .style files if applicable) +7. Localization (from lang.strings if applicable) +8. Build info and verification hooks +9. Reference implementations of similar features +10. Risks and unknowns + +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. + +Do not implement code in this phase. +``` + +## Phase 1F: Context (Follow-up Task, letter = `b`, `c`, ...) + +```text +You are the context phase for a follow-up task on an existing project in repository . + +NEW TASK: + +Read CLAUDE.md for the basic coding rules and guidelines. + +Steps: +1. Read AGENTS.md for project conventions. +2. Read .ai//about.md — the project-level blueprint describing everything done so far. +3. Read .ai///context.md — 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. +5. Search the codebase for any ADDITIONAL files, classes, functions, and patterns relevant to the new task but not already covered. +6. Read all newly relevant files thoroughly. + +Write TWO files: + +### File 1: .ai//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. You are rewriting it now so that the next follow-up has an accurate project overview to start from. + +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: +- 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") +- Any changed design decisions or architectural updates from the new task requirements + +It should NOT contain: +- Any temporal state: "Current State", "Pending Changes", "TODO", "Not yet implemented" +- History of how requirements changed between tasks +- References to "the old approach" vs "the new approach" +- 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 + +### File 2: .ai///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. + +It should contain: +- **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 (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. Do not implement code in this phase. ``` @@ -29,17 +130,19 @@ You are the planning phase for task "" in repository . Read CLAUDE.md for the basic coding rules and guidelines. Read: -- .ai//inputs.md -- .ai//context.md +- .ai///context.md + +Then read the specific source files referenced in context.md to understand the code deeply. Create: -- .ai//plan.md +- .ai///plan.md Plan requirements: 1. Concrete file-level edits -2. Ordered phases +2. Ordered phases (each phase implementable by a single agent, roughly <=8 steps) 3. Verification commands 4. Rollback/risk notes +5. Status section with checklist of phases, build verification, and code review ``` ## Phase 3: Implement @@ -50,17 +153,17 @@ You are the implementation phase for task "" in repository . Read CLAUDE.md for the basic coding rules and guidelines. Read: -- .ai//inputs.md -- .ai//context.md -- .ai//plan.md +- .ai///context.md +- .ai///plan.md Implement the plan in code. Then write: -- .ai//implementation.md +- .ai///implementation.md Include: 1. Files changed 2. What was implemented 3. Any deviations from plan and why +4. Update plan.md Status section to mark completed phases ``` ## Phase 4: Verify @@ -71,12 +174,12 @@ You are the verification phase for task "" in repository . Read CLAUDE.md for the basic coding rules and guidelines. Read: -- .ai//plan.md -- .ai//implementation.md +- .ai///plan.md +- .ai///implementation.md Run the relevant build/test commands from AGENTS.md and plan.md. Append results to: -- .ai//implementation.md +- .ai///implementation.md If blocked by locked files or access errors, stop and report exact blocker. ``` @@ -90,9 +193,9 @@ Read AGENTS.md for the basic coding rules and guidelines. Read REVIEW.md for the style and formatting rules you must enforce. Read: -- .ai//context.md -- .ai//plan.md -- .ai//implementation.md +- .ai///context.md +- .ai///plan.md +- .ai///implementation.md Run `git diff` to see all uncommitted changes made by the implementation. Implementation phases do not commit, so `git diff` shows exactly the current feature's changes. Then read the modified source files in full. @@ -108,7 +211,7 @@ Perform a code review using these criteria (in order of importance): 8. Style compliance: verify adherence to REVIEW.md rules and AGENTS.md conventions. Write: -- .ai//review.md +- .ai///review.md If issues are found, implement fixes and update implementation.md/review.md with final status. ``` @@ -116,9 +219,9 @@ If issues are found, implement fixes and update implementation.md/review.md with ## Example Runner Commands ```powershell -codex exec --json -C "" | Tee-Object .ai//logs/phase-1-context.jsonl -codex exec --json -C "" | Tee-Object .ai//logs/phase-2-plan.jsonl -codex exec --json -C "" | Tee-Object .ai//logs/phase-3-implement.jsonl -codex exec --json -C "" | Tee-Object .ai//logs/phase-4-verify.jsonl -codex exec --json -C "" | Tee-Object .ai//logs/phase-5-review.jsonl +codex exec --json -C "" | Tee-Object .ai///logs/phase-1-context.jsonl +codex exec --json -C "" | Tee-Object .ai///logs/phase-2-plan.jsonl +codex exec --json -C "" | Tee-Object .ai///logs/phase-3-implement.jsonl +codex exec --json -C "" | Tee-Object .ai///logs/phase-4-verify.jsonl +codex exec --json -C "" | Tee-Object .ai///logs/phase-5-review.jsonl ``` diff --git a/.codex/skills/task-think/SKILL.md b/.codex/skills/task-think/SKILL.md index b026e02899..19f1260a33 100644 --- a/.codex/skills/task-think/SKILL.md +++ b/.codex/skills/task-think/SKILL.md @@ -1,6 +1,6 @@ --- name: task-think -description: Orchestrate a multi-phase implementation workflow for this repository with artifact files under .ai/task-slug and optional fresh codex exec child runs per phase. Use when the user wants one prompt to drive context gathering, planning, implementation, 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/// and optional fresh codex exec child runs per phase. Use when the user wants one prompt to drive context gathering, planning, implementation, verification, and review iterations while keeping the main session context clean. --- # Task Pipeline @@ -11,21 +11,44 @@ Run a full implementation workflow with repository artifacts and clear phase bou Collect: - task description -- optional task slug (if missing, derive a short kebab-case name) +- optional project name (if missing, derive a short kebab-case name) - optional constraints (files, architecture, deadlines, risk tolerance) - optional screenshot paths -If screenshots are attached in UI but not present as files, write a brief textual summary in `.ai//inputs.md` so child runs can consume the requirements. +If screenshots are attached in UI but not present as files, write a brief textual summary in `.ai//about.md` so child runs can consume the requirements. + +## Overview + +The workflow is organized around **projects**. Each project lives in `.ai//` and can contain multiple sequential **tasks** (labeled `a`, `b`, `c`, ... `z`). + +Project structure: +``` +.ai// + about.md # Single source of truth for the entire project + a/ # First task + context.md # Gathered codebase context for this task + plan.md # Implementation plan + review.md # Code review document + b/ # Follow-up task + context.md + plan.md + review.md + 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. +- 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. ## Artifacts Create and maintain: -- `.ai//inputs.md` -- `.ai//context.md` -- `.ai//plan.md` -- `.ai//implementation.md` -- `.ai//review.md` -- `.ai//logs/phase-*.jsonl` (when running child `codex exec`) +- `.ai//about.md` +- `.ai///context.md` +- `.ai///plan.md` +- `.ai///implementation.md` +- `.ai///review.md` +- `.ai///logs/phase-*.jsonl` (when running child `codex exec`) ## Execution Mode @@ -33,12 +56,13 @@ Run `codex exec --json` child sessions for each phase. ## Fresh-Run Mode Procedure -1. Confirm repository root and task slug. -2. Create `.ai//` and `logs/`. -3. Run child phase sessions sequentially, waiting for each to finish. -4. After each phase, validate artifact file exists and has substantive content. -5. Summarize status in the parent session after each phase. -6. Stop immediately on blocking errors and report exact blocker. +1. Detect follow-up vs new project (check if first token of task description matches an existing project name with `about.md`). +2. For new projects: pick unique short name, create `.ai//` and `.ai//a/`. +3. For follow-up tasks: find latest task letter, create `.ai///`. +4. Run child phase sessions sequentially, waiting for each to finish. +5. After each phase, validate artifact file exists and has substantive content. +6. Summarize status in the parent session after each phase. +7. Stop immediately on blocking errors and report exact blocker. Use the phase prompt templates in `PROMPTS.md`. @@ -56,6 +80,7 @@ Mark complete only when: - plan phases are done - verification results are recorded - review issues are addressed or explicitly deferred with rationale +- Remind the user of the project name so they can request follow-up tasks within the same project. ## User Invocation @@ -63,4 +88,8 @@ 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.` +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` + If screenshots are relevant, include file paths in the same prompt. diff --git a/AGENTS.md b/AGENTS.md index 20f53c6669..78c64f84a7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -186,7 +186,15 @@ api().request(MTPnamespace_MethodName( **Key points:** - Always refer to `api.tl` for method signatures and return types - Use generated `MTP...` types for parameters (`MTP_int`, `MTP_string`, etc.) -- For multiple constructors, use `.match()` or check `.type()` then `.c_constructor()` +- For multiple constructors, use `.match()` or check `.type()` against `mtpc_` constants then call `.c_constructorName()`: + ```cpp + // Using match: + result.match([&](const MTPDuser &data) { ... }, [&](const MTPDuserEmpty &data) { ... }); + // Or explicit type check: + if (result.type() == mtpc_user) { + const auto &data = result.c_user(); // asserts on type mismatch + } + ``` - For single constructors, use `.data()` shortcut - Include `.handleFloodErrors()` before `.send()` in rare cases where you want special case flood error handling @@ -218,7 +226,8 @@ primaryButton: MyButtonStyle(defaultButton) { ``` **Built-in types:** -- `int` - Integer numbers +- `int` - Integer numbers (e.g., `maxLines: 3;`) +- `bool` - Boolean values (e.g., `useShadow: true;`) - `pixels` - Pixel values with `px` suffix (e.g., `10px`) - `color` - Named colors from `ui/colors.palette` - `icon` - Inline icon definition: `icon{{ "path/stem", color }}` @@ -229,6 +238,22 @@ primaryButton: MyButtonStyle(defaultButton) { - `font` - Font: `font(14px semibold)` - `double` - Floating point +**Multi-part icons** (layers drawn bottom-up): +```style +myComplexIcon: icon{ + { "gui/icons/background", iconBgColor }, + { "gui/icons/foreground", iconFgColor } +}; +``` + +**Borders** are typically separate fields, not a single property: +```style +chatInput { + border: 1px; // width + borderFg: defaultInputFieldBorder; // color +} +``` + **Never hardcode sizes in code:** The app supports different interface scale options. Style `px` values are automatically scaled at runtime, but raw integer constants in code are not. Never use hardcoded numbers for margins, paddings, spacing, sizes, coordinates, or any other dimensional values. Always define them in `.style` files and reference via `st::`. @@ -311,6 +336,20 @@ auto filesTextProducer = tr::lng_files_selected( - Placeholders use `lt_tag_name, value` pattern - For `{count}`: immediate uses `int`, reactive uses `rpl::producer` with `| tr::to_count()` - Move producers with `std::move` when passing to placeholders +- Rich text projectors — pass as the last argument to produce `TextWithEntities` instead of `QString`. These are smart objects with multiple `operator()` overloads: + - `tr::marked` — basic projection, converts `QString` to `TextWithEntities` + - `tr::rich` — interprets `**bold**`/`__italic__` markup in the string + - `tr::bold`, `tr::italic`, `tr::underline` — wrap text in that formatting + - `tr::link` — wrap as a clickable link + - `tr::url(u"https://..."_q)` — returns a projection that converts text to a link pointing to the given URL; can be passed to `rpl::map` or directly to a `tr::lng_...` call + ```cpp + auto title = tr::lng_export_progress_title(tr::now, tr::bold); + auto text = tr::lng_proxy_incorrect_secret(tr::now, tr::rich); + auto linked = tr::lng_settings_birthday_contacts( + lt_link, + tr::lng_settings_birthday_contacts_link(tr::url(link)), + tr::marked); + ``` ## RPL (Reactive Programming Library) @@ -370,9 +409,16 @@ std::move(merged) | rpl::on_next([=](QString &&value) { }, lifetime); ``` +**Other pipeline starters** — besides `rpl::on_next`, there are: +- `rpl::on_error([=](Error &&e) { ... }, lifetime)` — handle errors +- `rpl::on_done([=] { ... }, lifetime)` — handle stream completion +- `rpl::on_next_error_done(nextCb, errorCb, doneCb, lifetime)` — handle all three + +The `Error` template parameter defaults to `rpl::no_error`: `rpl::producer`. + **Key points:** - Explicitly `std::move` producers when starting pipelines - Pass `rpl::lifetime` to `on_...` methods or store returned lifetime - Use `rpl::duplicate(producer)` to reuse a producer multiple times -- Combined producers automatically unpack tuples in lambdas +- Combined producers automatically unpack tuples in lambdas (works with `rpl::map`, `rpl::filter`, and `rpl::on_next`)