focused-module-implementer

name	focused-module-implementer
description	Docs-first autonomous implementation for a user-specified module in this repository. Use when the user asks Codex to focus on one module and keep going autonomously, finish the next module slice, plan/code/test/commit/push in small atomic tasks, or explicitly says the budget is sufficient and Codex should not stop except for serious blockers.

Focused Module Implementer

Core Rule

Do not start coding before reading the relevant project and module documents. Treat the user-specified module as the focus boundary: understand what it owns, what it must not own, and which adjacent contracts it depends on before editing code.

Assume the user wants autonomous execution inside the repository's documented architecture boundaries. Plan when planning is useful, code when the next atomic task is clear, test before claiming progress, commit after each completed atomic task, and attempt to push. Only stage and commit files that belong to the current atomic task. If push fails, record the failure locally and continue with the next task unless the failure blocks local work.

Intake

1. Identify the module named by the user. If the module is ambiguous, ask one concise question.
2. Check git status --short before edits. Preserve unrelated tracked, untracked, and generated changes. If the worktree is dirty, record which files are yours to touch for this task.
3. If .artifacts/ai/ exists, use it as the local task record. Read the active plan/progress/findings/handoff enough to continue without duplicating work.
4. Define the smallest useful atomic task. Avoid large mixed tasks.
5. Write a short Done when: condition for the atomic task before editing. Include the behavior, test evidence, documentation update, and out-of-scope boundary.

Autonomous Design Policy

When another workflow pushes for upfront brainstorming or design approval, do not default to ceremony and do not default to rushed coding. Default to the best architecture decision that fits this repository:

• Module autonomy first: keep module business truth, retry rules, state projection, and scheduling semantics inside the focused module's own contracts, facade, driver, and ports.
• Program to interfaces: when external capability is needed, define or consume a narrow port/trait/DTO contract; put concrete wiring in composition-root.
• Keep coupling low: do not modify unrelated modules such as engines, fab, projects, settings, or account-auth to implement downloads behavior. Only touch shared kernel contracts, host transport, or composition-root wiring when the boundary is explicit, documented, and minimal.
• Keep backend/frontend separation strict: backend module work must not modify frontend files. Backend-focused tasks may touch backend crates, shared kernel contracts, host transport, and composition-root wiring when documented, but must not edit app/, components/, frontend routes, styles, or UI state. Frontend changes require an explicit frontend-focused user request or a separate atomic task.
• Extend without overbuilding: prefer stable DTOs, traits, pure mappers, and small helpers that can carry future work. Do not preemptively add full background scheduling, UI flows, diagnostics, or complex policies unless the current slice requires them.
• Prefer high-performance, maintainable code: pure functions before side effects, small read-only projections before mutating workflows, pagination/bounded scans before broad loads, and tests that prove boundaries precisely.
• Preserve layered ownership: domain/use-case logic lives in the module, shared runtime owns only generic job lifecycle, composition-root only assembles dependencies, host commands only map IPC, and frontend only consumes backend read models.

If there are 2-3 plausible approaches, compare them briefly in the task record, choose the one that best satisfies the policy above, and proceed. Do not stop merely because alternatives exist.

Stop and ask the user only when the best choice cannot be derived from docs and architecture principles:

• product semantics or user-visible behavior are genuinely undefined
• the only viable path requires changing an unrelated module's business logic
• the task requires a breaking public API/IPC/persisted schema change not already documented
• the change is destructive, security-sensitive, or operationally irreversible
• two approaches are equally good under the policy but lead to incompatible future architecture

When the task is broad, first narrow it into one autonomous slice, document the chosen approach and trade-offs in .artifacts/ai/ or the relevant module docs, then execute that slice. Use docs/superpowers/specs/ only when the user explicitly asks for that workflow or the task truly needs a standalone design artifact.

Subagent-Driven Mode

Do not use subagents by default. Enable this mode only when the user explicitly asks for subagents, subagent-driven work, delegation, parallel agents, or passes a command option such as --subagents.

The main agent remains the coordinator and architecture owner. It must read the documents, choose the architecture approach, define the atomic tasks, assign write scopes, review results, run final verification, stage, commit, and decide whether pushing is safe.

Prefer read-only subagents:

• Use explorer subagents to answer narrow codebase or documentation questions.
• Use reviewer subagents to check module boundaries, architecture fit, test evidence, and quality.
• Use worker subagents only when the task is fully specified and write scopes cannot conflict.

Supported modes:

• --subagents=review: read-only explorers/reviewers only. This is the safest default when subagents are requested without a specific mode.
• --subagents=worker: allow one write-capable worker for one narrow atomic task.
• --subagents=parallel: allow multiple write-capable workers only when their write sets are disjoint.

Before dispatching any write-capable worker, prepare a dispatch brief:

• module focus
• atomic task and Done when:
• required docs already identified
• allowed write set
• forbidden write set
• architecture constraints from the autonomous design policy
• exact tests or checks to run
• expected final report format

For backend module tasks, the forbidden write set must include frontend paths such as app/, components/, frontend route files, styles, and UI state unless the user explicitly requested frontend work in the current task.

Never dispatch parallel workers to edit the same file or the same hotspot area. Treat these as single-owner files unless a task explicitly says otherwise: driver.rs, facade/mod.rs, contracts/dto.rs, host command files, composition-root wiring, and active task protocol files.

Every worker result needs main-agent review before it can be accepted. Run a boundary review first, then a quality review:

• Boundary review checks module autonomy, interface ownership, unrelated-module changes, public API/schema/IPC scope, and documented out-of-scope boundaries.
• Quality review checks test precision, side effects, performance, overengineering, formatting, and maintainability.

If a subagent asks for context, provide only the minimum task-local context needed. If a worker reports blocked status, either provide missing context, split the task smaller, or take the task back locally. Do not force repeated attempts without a new hypothesis.

Required Reading Before Code

Always read these first:

• README.md
• CONTRIBUTING.md
• docs/README.md if present
• the active .artifacts/ai/ files when the repo task protocol is active
• module docs under docs/modules/<module>/

For a module with docs, read only that module's docs unless a cross-module boundary is truly involved:

• README_ARCH.md for ownership and boundaries
• README_API.md for public contracts
• README_FLOW.md for lifecycle and state transitions
• README_IMPL.md for implementation roadmap and current slice details

For the downloads module, treat these as the default required module docs:

• docs/modules/downloads/README_ARCH.md
• docs/modules/downloads/README_API.md
• docs/modules/downloads/README_FLOW.md
• docs/modules/downloads/README_IMPL.md

Read additional architecture docs only when they are relevant to the task:

• docs/TauriRewriteArchitectureBlueprint.md for overall architecture boundaries
• docs/TauriArchitecturePrinciplesDesign.md for ownership and layering principles
• docs/TauriBackendCrateLayoutAndUseCaseStubDesign.md for crate/module placement
• docs/TauriTestingStrategyAndQualityGateDesign.md for verification expectations
• docs/TauriAIDevelopmentTransactionProtocolDesign.md for task transaction rules
• docs/TauriIPCAndStateContractsDesign.md for IPC/state projection work
• docs/TauriKernelJobsRuntimeDesign.md for kernel job runtime, scheduler, or execution state work
• docs/TauriDownloadRuntimeDesign.md for downloads runtime or segment execution work
• docs/TauriErrorHandlingAndProjectionDesign.md for error mapping or state projection
• docs/TauriSecurityCredentialsAndPermissionsDesign.md for filesystem, credentials, permissions, or path safety
• docs/TauriCodeCommentStandard.md before adding non-obvious comments in Rust or TypeScript

Do not read unrelated module implementation docs just to be thorough. If touching another module, write down why it is in scope.

For large docs such as README_IMPL.md, read selectively after orientation: inspect headings, search with rg for the current slice, and load the relevant sections plus nearby context. Do not spend context on unrelated historical sections.

Context Summary Gate

Before editing, summarize locally or in the task record:

• module purpose
• owned crates/files likely involved
• public API or IPC surface affected
• out-of-scope areas
• tests that should prove the slice
• the next atomic task
• Done when: evidence for the atomic task
• expected write set and files that must stay out of scope
• the chosen architecture approach and why it is the best fit under the autonomous design policy
• whether subagent-driven mode is disabled or explicitly enabled, and which mode/write scopes are allowed

If this summary cannot be written, keep reading instead of coding.

Atomic Execution Loop

For each atomic task:

1. Update the local task record if .artifacts/ai/ is active.
2. Write or adjust the focused test first when behavior changes.
3. Implement the minimum code needed for the slice.
4. Add concise Chinese comments only for non-obvious logic or important boundaries. Do not comment obvious code.
5. Run the focused test. Then run the smallest broader gate that could catch integration regressions.
6. Update relevant docs when behavior, boundary, API, or roadmap status changes.
7. Record the exact verification commands and results in the task record.
8. Run git diff and git status --short.
9. Stage only the current atomic task files.
10. Run git diff --cached --name-status and confirm the staged scope is only the current atomic task.
11. Commit the completed atomic task.
12. Before pushing, run git log --oneline origin/<branch>..HEAD when a tracking branch exists. If it includes commits outside the current task or an unexpectedly large backlog, ask the user before pushing.
13. Attempt to push. If push fails for network/auth/remote reasons, record it and continue locally.

Keep each commit focused. Do not batch unrelated fixes into one task just because they are nearby.

Testing Expectations

Never say a task is complete without verification. Prefer focused commands first, then broader checks:

• Rust crate work: cargo test -p <crate> <test-name> then relevant crate/workspace checks
• Tauri host or composition work: include composition/desktop smoke tests when touched
• Frontend work: use npm run lint, npm run build, or targeted checks based on the changed surface. Run frontend checks only when the user explicitly focuses a frontend task or the approved atomic slice includes frontend files.
• Documentation-only work: run available format/link checks if present; otherwise inspect changed docs manually

If a command cannot run, record the exact reason and choose the next-best local proof.

For every completed atomic task, record actual evidence, not just a claim. Good entries look like cargo test -p launcher-module-downloads retry_summary --lib: passed or npm run lint: failed because dependency install is missing.

Failure Policy

Continue autonomously unless there is a serious blocker.

For a serious bug:

1. Reproduce or isolate it first.
2. Try up to five distinct fix attempts.
3. Count an attempt only when it has a hypothesis, a change or diagnostic action, and observed evidence. Re-running the same command without a new hypothesis is not a new attempt.
4. After each failed attempt, record what changed and what evidence was observed.
5. If five attempts fail, stop implementation, record the blocker in .artifacts/ai/handoff.md or another local task record, and tell the user what remains.

Do not spin indefinitely. Do not hide failed tests.

Boundaries

• Stay focused on the user-specified module.
• For backend module focus, do not modify frontend files such as app/, components/, frontend routes, styles, or UI state unless the user explicitly switches the task to frontend work.
• Do not move business truth into the frontend when backend ownership is documented.
• Do not change public DL_*, IPC, scheduler, manifest, SQLite, or composition-root contracts unless the current atomic task explicitly requires it.
• Do not rewrite architecture documents broadly as part of implementation.
• Do not revert unrelated user or agent changes.
• Do not skip documentation reading because the code looks obvious.