# Conversational commands

This is the default product interface after setup, for Claude, Codex and other agents
that read AGENTS.md. It is an instruction contract for the current agent, not a shell
parser or a background daemon. Interpret user intent in Vietnamese or English; do not
require slash commands, exact syntax or capitalization. Quoted examples, documentation
and questions about commands are not authorization to execute them.

## Resolve context before acting

1. Run `./bsa.sh status` yourself and read the relevant truth, sprint record and feedback.
2. Resolve the requested sprint against existing `.bsa/sprints/*.json` IDs first. An
   exact existing ID wins. Otherwise a numeric reference `1`, `01`, `001`, `sprint 1`
   or `S001` refers to S001; `12` to S012; numbers beyond 999 keep all digits. Use
   positive integers for delivery sprints. `sprint 0`, `S000`, `discovery` or
   `phase đầu tiên` mean Sprint 0, a discovery sprint: start it with `--kind discovery`.
   Preserve explicit custom IDs such as release-beta.
   If multiple existing IDs could match a numeric reference, ask which one instead
   of guessing or creating another sprint. Never treat a missing explicit ID as the
   active sprint silently.
3. With no sprint ID, target the active sprint. If none exists, explain that briefly
   and ask which sprint to start. Read-only status never starts a sprint.
4. If another sprint is active, explain the conflict and ask which work to continue;
   never close, discard or switch it implicitly. Sealed sprints are immutable. A start
   request for a sealed sprint reports that it is closed and asks for a new sprint ID.
5. A new sprint needs a meaningful goal. Use the goal in the message, established chat
   context, or an explicitly assigned sprint goal in project planning documents. Do
   not choose an arbitrary backlog item or use "Sprint 1" as a product goal. When
   `status` shows a current `backlog` from a sealed Sprint 0, propose the goal from its
   `remaining` stories (highest priority, suggested for this sprint, dependencies met) and
   start once the user agrees or named those stories. If no goal can be established, ask
   one short question, e.g. "Sprint 1 cần đạt mục tiêu gì?". This is a product question;
   do not ask the user to run `start --goal`.
6. Sprint 0 needs the user's business goal, e.g. "sprint 0: bán vé sự kiện online cho
   CLB". Offer Sprint 0 when a user starts sprint 1 with only a broad product idea and no
   backlog exists; do not force it on a user who already knows the sprint's scope.

## Intent mapping and stop rules

Internal commands below are executed BY THE AGENT. Never return them as homework.

| User message / equivalent | Agent action | Finish at |
|---|---|---|
| `start sprint 1`, `bắt đầu sprint 1` | Resolve goal; invoke `start S001 --goal ...` for a new sprint, or `start S001` to resume; execute the phase loop below | Reconcile complete, ready to seal |
| `start sprint 1: xây tính năng đăng nhập` | Use the stated goal; start and execute | Ready to seal |
| `sprint 0: <mục tiêu>`, `start sprint 0`, `discovery`, `làm rõ yêu cầu và lên backlog` | Resolve the goal; invoke `start S000 --kind discovery --goal ...`; run `discovery` then `backlog` as a brainstorm with the user | Backlog assessed, ready to seal |
| `sprint 0 từ dự án cũ <path>`, `tạo backlog từ source code ...`, `reverse engineer yêu cầu từ hệ thống cũ` | Resolve the old system's paths (an explicit path; otherwise existing code under apps/ or legacy docs in the workspace, confirmed with the user); invoke `start S000 --kind discovery --goal ... --source NAME=PATH` per source; run discovery with the inventory, then backlog | Backlog assessed, ready to seal |
| `thêm nguồn <path>` during an active discovery sprint | `start S000 --source NAME=PATH` adds the source; completed discovery phases go stale and are redone | Discovery revalidated |
| `backlog`, `lên backlog`, `brainstorm backlog` | Run the backlog phase of the active discovery sprint, completing discovery first | Backlog phase completed |
| `continue sprint 1`, `resume`, `tiếp tục sprint 1` | Resume the active matching sprint from status.next; do not reset | Ready to seal |
| `brainstorm`, `product`, `spec`, `arch`, `architecture`, `design`, `plan`, `implement`, `test`, `review`, `reconcile` (optionally `sprint 1`) | Run the requested phase, executing missing/stale prerequisite phases first; spec maps to product, architecture to arch | Requested phase completed |
| `feedback: thêm đăng nhập Google`, `feedback sprint 1: ...`, `sửa design: ...` | Record feedback against the matching active sprint, assess impact and apply it; revalidate gates and rerun affected implementation/test/review | Ready to seal, or the user's explicit narrower boundary |
| `seal sprint 1`, `đóng sprint 1` | Finish remaining/stale phases within the established sprint goal; reconcile; run `seal --dry-run`, inspect diff, then `seal`; update `docs/go-live-checklist.md` (process.md) | Published truth, sealed sprint, updated go-live checklist |
| `start sprint 1 ... và tự đóng khi xong`, `run sprint 1 through seal` | Start/resume, run the complete loop, preview and seal; update the go-live checklist | Published truth, sealed sprint, updated go-live checklist |
| `status`, `sprint 1 đến đâu rồi?` | Read status; for a named sealed/non-active sprint inspect its record without switching the active sprint | A short progress/blocker answer |
| `audit`, `kiểm tra living truth` | Run audit and explain integrity findings | Report only |
| `auto`, `chạy tự động`, `run unattended`, `chạy hết sprint không cần tôi` | Run `auto` with the configured runner (per-role via `runner_commands`, otherwise `runner_command`); report the termination condition and what it needs next | Reported stop condition |
| `evidence`, `bundle`, `bằng chứng` | Run `evidence`; summarize verified behaviors, open gaps, preservation constraints and regressions for the active sprint | Report only |
| `resolve F-...: <answer>`, `quyết định F-...` | Record the user's actual answer with `decide`, apply it and revalidate | Finding applied and revalidated |

Respect qualifiers over these defaults: "chỉ brainstorm", "dừng sau plan", "chỉ ghi
feedback", "chỉ xem trước seal" all narrow the work. For record-only feedback, record
it without applying changes. For seal preview only, do not publish. A feedback message
without content needs one short clarification. A new goal for an already-active sprint
is feedback, not a reset or a silent change to its original goal. Repeating seal on the
same sealed sprint is a read-only confirmation after checking its record and integrity;
never seal a different active sprint by accident.

## Sprint 0 is a conversation

Discovery and backlog are brainstormed with the user, so they are the exception to "do
not add routine confirmations": ask the clarifying questions in the phase procedure, show
the proposed business requirements and then the proposed epics, stories and priorities,
and write the artifacts from the user's answers. Keep rounds short and offer defaults.
Do not simulate the user's answers, and do not run Sprint 0 through the unattended loop
unless the user already supplied the answers; an unanswered business choice is a human
finding. From an existing project, show the user the reconstructed capabilities and ask
them to confirm the inferred ones and to choose keep, change or retire before writing the
backlog. The goal may come from the message ("tái hiện yêu cầu nghiệp vụ của hệ thống cũ
và lên backlog chuyển đổi"); still ask what the business wants next. Sealing Sprint 0 publishes no truth. It makes its backlog the current one, which
`status` reports under `backlog` with delivered and remaining stories.

## Execute the phase loop

The current conversation agent does the work. Do not configure or invoke an external
runner unless the user explicitly requests unattended/external execution.

1. Read status.next and obtain phase instructions using the corresponding CLI command
   (or `pipeline` for the next phase). Read and follow the returned prompt immediately.
2. Create the actual artifacts, implementation and tests. Configure meaningful tests
   yourself from the project's stack during brainstorm. Do not stop at scaffolding.
3. After finalizing a phase, obtain `context PHASE`, write the assessment
   (`validate PHASE --report ...`) under sprint evidence, then `complete PHASE --report ...`.
   The assessment and the phase report must carry different `agent` identities, so assess
   as a reviewer role that did not author the phase. Test completion requires `test --run`
   followed by that assessment. Never ask the user to fill reports or copy internal commands.
4. Read status again, resolve failures and revalidate stale gates. Continue until the
   boundary authorized by the user's message is reached. Don't wait for a new chat
   command between every phase of a start/continue request.
5. Seal only when requested or included in the authorized boundary. Missing gates
   require actual work, not a bypass. Ask only for essential business input, unresolved
   conflicts or permissions the agent cannot supply. Do not add routine confirmations.

For a single-phase request whose phase is already complete and fresh, report its
current result; rerun only if requested or if new feedback is present. Revalidating
prerequisites must not silently extend the requested phase boundary.

## Reporting

Briefly state the sprint, outcome and next available action. Link useful artifacts.
For example: "Sprint 1 đã hoàn tất implement, test và review, sẵn sàng đóng. Bạn có
thể nhắn `seal sprint 1`." For a phase request, report that phase's result. Include
real blockers and failed checks rather than claiming completion. Do not call a sprint
sealed while it is merely ready to seal. Never request API keys or authentication
just to handle these commands inside an already-running agent conversation.

## Quality validation and human decisions

`validate [phase] [sprint N]` invokes workflows/validate.md. With no phase use the first
incomplete phase (reconcile when ready to seal). Do not advance beyond the requested review.
`resolve F-ID: <answer>` records the user's actual decision using `decide`, applies it and
revalidates. `status` exposes awaiting_decisions. Continue/start/pipeline must pause affected
work for unanswered human findings and present options. Simple repairs remain autonomous.

The `auto` loop needs an external runner, so ask before configuring one unless the user
requested unattended execution. It runs a phase in two processes — the phase's role authors
it, the counterpart role assesses it — and completes the phase itself once the assessment
passes, so a run that stops between the two resumes without redoing either. With
`runner_commands` a role can have its own agent; if a role and its counterpart share one
runner the loop warns and records `independent_assessment: false` for those iterations
rather than claiming a review it did not get. When it stops, report the reason it gives:
`human_decision` needs the user's answer, `regression` needs the last verified state
restored or its test re-added, `no_progress` needs the blocking failure diagnosed, `budget`
only needs another run. Never treat a stop as a silent success, and never answer a human
finding to unblock it.

An unattended loop can be cut off before it reports anything: the machine goes down, the
process is killed, the provider stops answering. Its run record stays `state: running`, and
`status` lists it under `unfinished_runs` — `live: true` means the recorded process is still
there writing. Report that run rather than restarting over it, and if the process is provably
gone re-run with `--resume`; the taken-over record becomes `superseded` so the history stays
readable. `--resume` never answers a question on the user's behalf and never re-runs a phase
whose artifacts are already verified by digest — it only says "the previous loop is not
still working here".