feature-development-workflow

Feature Development Workflow

📋 Responsibilities

Specify the standard development process for agentbay-cli when receivingany new requirement, covering the full-chain operation specification from pulling a branch, local development, build verification, commit, and push to opening a PR.

This skill does not contain any specific requirement's code implementation details, and only constrains the process itself.

🎯 Trigger scenarios

Triggered when the user raises the following requests:

• "Develop an XX feature/command"
• "Add an XX requirement"
• "Start a new requirement"
• "Start XX according to the development process"
• Any requirement that needs a new feat branch for development

🌐 Remote repository topology

This project keeps only two remotes,and does not use upstream (personal fork):

Remote	Address	Purpose
origin	git@gitlab.alibaba-inc.com:InnoArchClub/agentbay-cli.git	Intranet code repository, archiving/collaboration/CI
aliyun	git@github.com:aliyun/agentbay-cli.git	The real customer-facing code repository, the target for merging into the mainline

Verification command:

git remote -v
# 必须只有 origin 和 aliyun,不允许出现 upstream

If extra remotes appear:

git remote remove <name>

📒 Change Record dual paths

To give every requirement a complete traceability chain of "requirement → design → code → commit → PR → release", before starting any new requirement you mustchoose one of the twoto establish a change record; both paths are mandatory, and the purpose is the same — to leave a reviewable record in the Git repository:

Path	Trigger scenario	Artifact location	Remarks
A. Qoder Quest Mode	Through ⌘ E enter Quest mode, have AI generate the Spec during the Design phase, and after Review click Download	.qoder/specs/<feature>.md(the default disk write location for Qoder client Download, zero configuration)	Recommended for complex requirements; Spec can be collaboratively edited with AI; files are untracked by default and need git add to be added to the repository
B. Manual CR directory	Quest Mode not enabled / lightweight requirements / existing external design drafts need to be retained	.qoder/changes/CR-<YYYY-MM-DD>-<feature-name>/	Contains spec.md / design.md / tasks.md / decisions.md / test-plan.md / rollback.md / trace.md, etc.

Core rules:

• When a requirement starts, choose one of the two;it is not allowed to skip both
• Under Quest Mode, .qoder/specs/<feature>.md is automatically written to disk by Qoder after clicking Download,must git add be included in the version repository, to avoid the record being disconnected from the code
• In non-Quest scenarios, you must manually create a CR directory under .qoder/changes/ , and the naming must strictly follow the CR-<YYYY-MM-DD>-<feature-name> format, strongly associated with the feat branch name
• The artifacts of both paths should ultimately be registered in trace.md / the corresponding Spec: feat branch name, key commit SHA, push target remote, PR link, merge commit, release tag

🚀 Standard development process (Task order must not be reversed)

Phase 0: Change record initialization (starting point of the traceability chain)

⚠️ Iron rule: before this Phase produces output,it is not allowed to enter Phase 1 to pull a branch。

Choose one path to establish the record:

Path A · Quest Mode (recommended)

1. ⌘ E Open the Quest panel
2. New Task → check the relevant files as Context → paste the requirement description → press Enter (Do not check Execute Directly, otherwise skipping the Design phase will not generate a Spec)
3. Wait for Qoder to generate the Spec in the Design phase (displayed streaming in the Spec Tab on the right)
4. Collaborate with AI to iterate on the Spec in the chat area; once satisfied, click Run Spec to proceed to execution
5. Key: In the top-right corner of the Spec Tab, click Download → the Qoder client will automatically write .qoder/specs/<feature>.md(the filename is generated based on the slug of the Spec title, zero configuration)
6. The Spec file is untracked by default; in subsequent commits it must also be git add included in the repository

Path B · Manual CR directory

1. mkdir -p .qoder/changes/CR-$(date +%F)-<feature-name>
2. Refer to .qoder/changes/TEMPLATE.md(if it exists) to establish:
   • spec.md: requirements background / goals / non-goals / scope
   • design.md: interface design / flowcharts / state machines
   • tasks.md: task breakdown (recommended to map to todo_write's tasklist)
   • decisions.md: key decisions (interaction defaults / parameter naming / branching strategy, etc.)
   • test-plan.md: unit tests / integration / regression
   • rollback.md: rollback plan
   • trace.md: traceability chain for subsequent continuous updates (branches / commits / push / PR / release)
3. Create the documentation first before pulling the feat branch, ensuring that the first commit of Phase 1 can enter the repository with the documentation

Phase 1: Requirements kickoff (branch preparation)

⚠️ Important: Before any code-writing action, a clean feat branch with the correct starting point must be determined; direct changes on master are prohibited.

1. Sync the latest status of both remotes

   git fetch origin
   git fetch aliyun
   

2. Determine whether the current feat branch can be reused(to avoid creating a new one every time)

   First read the current repository status:

   git branch --show-current           # 当前分支名
   git status --short                  # 工作区是否干净
   git log --oneline aliyun/master..HEAD -1   # 是否领先 aliyun/master
   git log --oneline HEAD..aliyun/master -1   # 是否落后 aliyun/master
   

   Necessary and sufficient conditions for reuse(all must be satisfied):

   • The current branch starts with feat- or feat/ , andis not master / main
   • The working tree is clean (git status --short output is empty; exceptions are allowed for uncommitted change documents, but they must be committed together later)
   • The current branchis not behind aliyun/master(i.e., HEAD..aliyun/master is empty; if behind, first rebase or have the user confirm the handling strategy)
   • The current branch topic is related to the new requirement, and the user explicitly agrees to reuse it

   Decision dispatch:

   • ✅ All satisfied → Actively ask the user:

     "Detected that you are currently on the feat/xxx branch, already synced with aliyun/master and the working tree is clean. Would you like to directly reuse the current branch to continue development, or from aliyun/master create a new feat branch?"

   • ❌ Any unsatisfied → Still must ask the user first(⚠️ must not automatically create a new branch):

     "The current branch is <branch-name>, [briefly describe the unsatisfied conditions, e.g., behind aliyun/master / uncommitted changes in the working tree / branch name does not start with feat-]. Please confirm: would you like to continue development on the current branch, or from aliyun/master create a new feat branch？"

     User chooses to continue the current branch → Skip step 3 and go directly to Phase 2 (the user bears the risk of the branch state). User chooses to create a new branch → Follow step 3.

3. Create a new feat branch (default path)

   Create based on aliyun/master (with the aliyun mainline as the source of truth):

   git checkout -b feat-<feature-name> aliyun/master
   

   Branch naming convention: feat-<短横线分隔的需求关键词>, e.g. feat-image-delete、feat-apikey-concurrency。

4. Confirm the final branch state:

   git log --oneline -1
   git status
   

   Whether reusing or creating a new branch, all subsequent actions in Phases 2-6 are performed on this feat branch.

Phase 2: Local development

Strictly follow the development.md rules:

• Interface changes must synchronize all mock classes
• New/modified commands must synchronize the README and external documentation
• Documentation synchronization follows the update-cli-command-docs skill (automatically delegated by create-cli-command Phase 5, or triggered independently)
• During daily development, the CHANGELOG only does readiness; generation/translation/backfilling of the release version section follows the bilingual-changelog-release skill
• New commands must have unit tests
• Parameters use named parameters (--name), not positional parameters

Development processAny automatic push action is prohibited。

Phase 3: Build and test verification

Full local verification is required before every commit:

go build -o agentbay .
go test ./... -count=1

Only after both commands pass can you proceed to the commit step.go build -o agentbay . An executable binary must be generated in the project root directory; you cannot use only go build ./... as a substitute.

Phase 4: Local commit (per user instruction)

⚠️ Iron rule:Before explicit user instruction, you must not execute git add / git commit。

After the user instructs a commit:

1. First show the changes, for user review:

   git status
   git diff --stat
   

2. Use the Conventional Commits specification(to ensure release-prep can correctly generate the CHANGELOG):

   git add -A
   git commit -m "<type>(<scope>): <description>
   
   - 具体改动点 1
   - 具体改动点 2
   - 具体改动点 3"
   

   <type> Choose from the following: feat / fix / docs / refactor / perf / revert / test / style / chore / ci / build. For user-perceivable changes, prefer those that will enter the CHANGELOG feat / fix / docs / refactor / perf / revert；<scope> prefer to use apikey、image、network、skills、docker、core、client. Breaking changes must use ! or footer BREAKING CHANGE:。

3. Confirm the commit result:

   git log --oneline -3
   

4. Update the change record:

   • Path A: Check whether .qoder/specs/<feature>.md has been included in this commit
   • Path B: Append this commit SHA and motivation summary to .qoder/changes/CR-xxx/trace.md

Phase 5: Push to remote (per user instruction)

⚠️ Iron rule:Before explicit user instruction to push, you must not execute any git push。

The push timing and target are determined by the user,only pushing to origin and aliyunis allowed; push command templates:

• Push to origin (intranet archive):

  git push origin feat-<feature-name>
  

• Push to aliyun (customer-facing mainline, PR source branch):

  git push aliyun feat-<feature-name>
  

• Push to both remotes at the same time(if the user requests):

  git push origin feat-<feature-name>
  git push aliyun feat-<feature-name>
  

Prohibited operations:

• ❌ git push --force / git push -f to any remote (unless explicitly authorized by the user)
• ❌ Push to the master / main main branch
• ❌ Push to the removed upstream
• ❌ Use --no-verify to skip hooks

After the push is complete:

• Record the push time and target remote in the change record's trace.md(Path B) or the Spec's "Execution Record" section (Path A)

Phase 6: Submit a PR (per user instruction)

After the feat branch has been pushed to aliyun , the user creates a PR via the GitHub web UI or the gh CLI to aliyun/master. The PR template requires:

• The title reuses the commit message title and keeps the Conventional Commits format, so release-prep can generate the CHANGELOG
• The description includes: requirement background / changes / testing status / risk notes

PR merge is approved by the user (or a designated reviewer). Cleanup actions after merge:

git checkout master
git fetch aliyun
git reset --hard aliyun/master
git branch -D feat-<feature-name>                # 本地删除
git push origin --delete feat-<feature-name>      # origin 删除
git push aliyun --delete feat-<feature-name>      # aliyun 删除(可选,或由 PR 合并页勾选)

Archive filing:

• In the CR's trace.md(Path B) or the Quest Spec (Path A), record the PR link, merge commit, and corresponding release tag
• Keep the archive directory in the repository,do not delete it, as a historical traceability asset

Phase 7: Release Handoff (triggered only for release requirements)

If the user requests to continue the release, prepare a tag, generate GitHub Release notes, or backfill historical release bodies,immediately load bilingual-changelog-release skill, and execute according to its SOP:

make release-prep VERSION=X.Y.Z

Note: After completing daily feature branch development, do not run git-cliff -o CHANGELOG.md or make changelogin this workflow; the CHANGELOG version section is generated and translated uniformly during the release phase.

🔒 Key Principles

1. Explicit Authorization Principle:commit and push are both executed only after explicit user instruction
2. Branch Switching Confirmation First Principle: When developing a new feature or requirement, if switching to a feat branch is needed,you must first ask the user for confirmation, and must not switch automatically — the user may be continuing iteration on the current branch
3. Source of Truth Principle: The feat branch is pulled from aliyun/master , ensuring the starting point is the customer-facing mainline
4. Dual Remote Principle: Pushing is limited to origin and aliyun, with no additional forks introduced
5. Rollback Principle: Every commit must be a stable state that has passed local verification
6. Branch Isolation Principle: Each requirement has an independent feat branch; mixing multiple requirements is prohibited
7. Traceability Principle: Each requirement must have an archive established under .qoder/specs/(Quest Mode Download automatically persists to disk) or .qoder/changes/(manual CR), and the archive is committed to the repository together with the code

✅ Process Checklist

Before requirement startup:

• git remote -v only has origin and aliyun
• has executed git fetch aliyun
• the current HEAD is on a feat branch (either newly created or an existing feat branch reused with user confirmation)
• if reused: the three conditions "not behind aliyun/master + clean working tree + user consent" are satisfied
• the change archive has been established (.qoder/specs/<feature>.md Quest Spec or .qoder/changes/CR-xxx/ directory)

Before commit:

• go build -o agentbay . passed and the root directory binary has been generated
• go test ./... -count=1 passed
• README / external documentation / unit tests / mock classes have all been synchronized
• CHANGELOG readiness has been completed: commit/PR titles conform to Conventional Commits, with command group scope when necessary
• git status no unexpected changes
• the change archive file has been git add, committed together with the code
• user commit authorization has been obtained

Before push:

• user push authorization has been obtained
• Clarify the user-specified target remote (origin / aliyun / both)
• The branch name starts with feat- , not master
• trace.md / Quest Spec has been updated with this push intent

📚 Related Rules

• development.md - Code standards / Mock sync / Commit standards
• create-cli-command - Specific implementation flow of CLI command wrappers
• update-cli-command-docs - docs/README documentation sync and CHANGELOG readiness
• bilingual-changelog-release - Bilingual CHANGELOG and GitHub Release notes SOP during the release phase

⚠️ Common Pitfalls

Pitfall	Symptom	Avoidance
Directly modifying on master	git status Shows HEAD is master and there is a diff	Before development, first git checkout -b feat-xxx aliyun/master
start from origin/master	The feat branch base lags behind the aliyun mainline, and the PR has conflicts	Explicitly branch from aliyun/master pull the branch
Blindly reusing an old feat branch	Reused a branch that lags behind aliyun/master or has leftovers in the working tree, contaminating the new requirement	Phase 1 Step 2 validates by necessary and sufficient conditions; if any is not satisfied, first ask the user's preference and let the user decide whether to continue on the current branch or switch to a new one
Unauthorized automatic push	Pushed before the user reviewed	The push action must wait for the user to say "推送"/"push"
Missed mock changes cause CI errors	*mockClient does not implement agentbay.Client	Immediately after an interface change grep -r "type mock.*Client struct" complete all of them
Residual upstream	git remote -v still has a personal fork	Execute git remote remove upstream
Missing change record	The requirement is completed but the repository has no Spec / CR directory, so it cannot be traced later	When starting a requirement, follow Phase 0 to force a choice of one of two options to create the record
Quest skips Design	Execute Directly was checked, so the Spec was never generated at all	When creating a New Task, confirm Execute Directly is unchecked, click Download to write to disk to .qoder/specs/
Record and code are disconnected	The Spec was created but was not git add, and the record is lost after merging	Before committing, check git status to ensure the Spec/CR files have entered the staging area