Feature Development Workflow

Use this workflow when implementing a feature in qwen-code that needs design, behavioral validation, or coordinated changes across multiple files. Each phase produces a concrete artifact. Do not combine phases; the output of each phase feeds the next.

Artifact Paths

Use these paths for planning artifacts:

• docs/design/<feature>.md
• .qwen/e2e-tests/<feature>.md

Phase 1: Investigate

Understand the requested behavior and the current qwen-code implementation.

Use a code exploration agent when available. Ask it to inspect the relevant qwen-code areas for:

• Existing feature definitions: tools, parameters, schemas, commands, UI, or config.
• Runtime wiring: spawning, lifecycle, state, permissions, hooks, and cleanup.
• Edge cases and error handling.
• Integration points and limitations.

In parallel, inspect docs, issues, tests, and nearby implementations that define or constrain the expected behavior. If no exploration agent is available, do the same investigation locally.

Output: mental model of current behavior, desired behavior, constraints, and key file paths with line numbers.

Phase 2: Design Doc

Write a design doc covering:

• Problem statement and current state, including the behavior gap.
• Proposed changes by layer or component.
• Key design decisions and rationale.
• Files affected.
• Scope boundaries.
• Open questions.

Use prose, tables, and bullets. Avoid code snippets unless essential for a key data structure. JSON config examples are acceptable.

Output: design doc on disk.

Phase 3: Test Plan

Use the e2e-testing skill to choose test modes. Then write an E2E test plan covering:

• Test groups by capability: parameter acceptance, core behavior, error handling, cleanup, and regressions.
• Exact commands and expected behavior before and after implementation.
• Unique tmux session names and temp dirs for independent groups.
• Which groups can be run in parallel by separate test-engineer agents.

Output: test plan on disk.

Phase 4: Dry-Run

Validate the test plan against the current baseline using the globally installed qwen CLI, not the local build.

Spawn test-engineer agents for independent test groups when the runtime supports it. The feature is not implemented yet, so tests should either fail or show the gap. Iterate the test plan if the dry-run reveals broken commands, wrong filters, or false positives.

Output: confirmed-working test plan with accurate pre-implementation baseline.

Phase 5: Implement

Read the relevant source files before editing. Implement the changes described in the design doc and follow project conventions:

• ESM and strict TypeScript.
• Prettier formatting.
• Collocated tests next to source.
• No speculative abstractions beyond the design.

After implementation:

npm run build
npm run typecheck
npm run bundle

Also run focused unit tests for changed files from the relevant package directory.

Output: local implementation that builds and passes focused tests.

Phase 6: Verify

Run the full E2E test plan against the local build with node dist/cli.js. Spawn independent test-engineer agents when useful and available.

If tests fail, diagnose, fix, rebuild, re-bundle, and re-test until all groups pass.

Output: E2E results appended to the test plan.

Phase 7: Self-Audit and Code Review

First self-audit the full diff per the self-audit step in AGENTS.md's General workflow (open-ended passes plus presume-wrong verification, until two consecutive clean passes). If the audit changes source, return through Phases 5-6 before resuming it. Then run /review with a review task listing all changed files. Triage each comment before acting:

• Valid: real bug or meaningful improvement. Fix it.
• False positive: reviewer missed context. Skip it.
• Overthinking: technically plausible but not worth the complexity. Skip it.

After fixes, re-run unit tests and a quick E2E sanity check.

Output: clean implementation with valid review findings addressed.

Phase 8: Wrap Up

Skip unless the user asks. Create the branch, commit with Conventional Commits, push, and create a draft PR using the project PR template. Post E2E results as a separate PR comment when applicable.

Iteration Rules

• If Phase 6 fails, return to Phase 5 and then re-run Phase 6.
• If Phase 7 finds valid issues, fix them, run a quick Phase 6 sanity check, and re-run the self-audit.
• Do not loop more than 3 times between Phases 5-7 without asking the user.
• If the test plan is inaccurate, update it and document why.