aimship 0.1.0-preview.4 → 0.1.0-preview.8

package/docs/guide.md

@@ -1,59 +1,210 @@
-# Using Aimship
+# Aimship Guide
 
-## Describe the work and its endpoint
+[中文](guide.zh-CN.md) · [README](../README.md)
 
-Explicitly select Aimship and say what result you want, where the relevant materials/code are, and how far the agent may proceed. An existing clear instruction is enough; you do not need to prepare a complete PRD. A design-only goal may need no code repository.
+This guide explains what to provide, how the agent proceeds and where to find results in common situations. You do not need to memorize stage names or fixed prompts.
 
-The agent records the original request and current requirements/Scope, proposes the stages needed for this goal, and explains meaningful choices. Once the arrangement is accepted, it remains the execution order. You decide material business, scope, compatibility, cost or data choices; routine engineering choices do not require repeated approval. Silence does not approve an unanswered proposal.
+<a id="install"></a>
+If Aimship is not installed yet, start with the README's [installation instructions](../README.md#install).
 
-Materials default to a delivery folder beneath `~/Aimship`, configurable at installation. Code remains in place, linked by repository identity and location in the delivery state. The material directory need not be the host's main workspace. Access is handled when an actual operation needs it; the agent must not silently move the materials or disable host controls.
+[Select Aimship](#hosts) · [Start from your situation](#start) · [Proceed and review](#review) · [Progress and results](#results) · [Changing requirements](#changes) · [Sessions and continuation](#continue) · [Parallel work](#parallel) · [Complete delivery](#completion) · [Usage problems](#troubleshoot)
 
-## Work on two requests at once
+<a id="hosts"></a>
+<a id="1-select-aimship-in-your-host"></a>
+<a id="1-select-aimship-in-your-ai-development-tool"></a>
+## 1. Select Aimship in your AI tool
 
-You can keep `~/Aimship/notification-preferences/` and `~/Aimship/invoice-export/` active at the same time. Each has its own goal, stages and state, with one writing session per delivery. They may use different repositories or the same repository.
+After installation, open a new tool session and select Aimship:
 
-For example, request A is implementing in an app checkout while request B is designing invoice export using that code as a read-only reference. B may continue design after a brief overlap note. Before B writes code, the agent checks the recorded work again: if both would edit A's checkout, use your existing choice to implement sequentially or use a separate worktree/checkout. If B already has an isolated worktree, reuse it. Neither file isolation nor finishing B's branch means the changes are already merged or business-compatible. The handoff names the actual code directories, branch/commit, uncommitted work and pending integration.
+| AI tool | How to select it | If it is missing |
+| --- | --- | --- |
+| Codex | Choose Aimship in the Skill selector; use `$aimship` in CLI | Start a new conversation or restart the CLI; restart the app if the list is stale |
+| Cursor | Use `/aimship` | Start a new agent session and inspect Customize → Skills; restart Cursor if stale |
+| Claude Code | Use `/aimship` | Start a new session and inspect the slash-command list; restart Claude Code if stale |
 
-When code scope is associated/changed, implementation begins or a working directory changes, the agent checks accessible delivery states in known material roots, including older unfinished deliveries rather than only recent ones. It reads focused Scope/plan sections only if needed. Ended deliveries are not counted as active writers; their pending integration may still be a dependency. Known shared interfaces, databases or test resources are arranged in the existing plan, even across different repositories.
+Each tool needs its own login, available model and access to delivery materials and relevant code repositories. Grant access when an operation needs it. Delivery materials are stored separately; code stays in its existing repository.
 
-This reports overlaps found in recorded deliveries. Stale records, inaccessible or unknown custom roots and work outside Aimship can hide overlaps. No matching record is not a guarantee of safety. There is no global lock, automatic worktree creation, agent scheduling or automatic merge; the agent preserves existing branches and unknown changes.
+AI tool integrations are experimental: actual Skill discovery, directory access and continuation across AI tools remain unverified. Healthy installation files do not prove that a tool loaded the Skill. Codex and Cursor share an entry, and compatible tools may discover entries in other locations; inspect paths and versions if duplicates appear, preserving unrelated or customized content. See the official [Cursor documentation](https://cursor.com/docs/skills) and [Codex skill locations](https://learn.chatgpt.com/docs/build-skills) for tool behavior.
 
-## Keep only useful artifacts
+<a id="start"></a>
+<a id="describe-the-work-and-its-endpoint"></a>
+## 2. Start from your current situation
 
-Every delivery has current requirements and state, with the original request traceable. A small fix can use a short requirement, state, and a results document with separate diagnosis/review/verification/handoff sections. A larger feature can have interaction, technical design, contracts, a batch plan and test cases. Unselected responsibilities do not produce empty templates.
+### Starting with an idea
 
-External PRDs, prototypes and images remain unchanged. Scope identifies their adopted versions, requirement mappings, conflicts and decisions. A link alone may not preserve a source version. Text extraction, visual inspection, browser interaction and original-format editing are different capabilities; the agent must identify missing parts.
+Describe the problem, who it affects, the expected change and known constraints. Include screenshots, discussion notes or references if available; a complete PRD is not required.
 
-Reuse existing engineering HTTP contracts. If database structures or data change, the design links a separate delivery-local SQL file with its dialect and conditions. SQL is a normal deliverable: generating it does not authorize changing migrations or running it.
+The agent clarifies gaps that affect scope and acceptance, organizes requirements, and proposes the stages and execution order. After you confirm the goal and important tradeoffs, work proceeds. Requirements and acceptance criteria are usually recorded in `prd.md`; open `status.md` for current progress.
 
-## Review, verify and change
+### Working from an existing PRD, prototype or other materials
 
-For multiple batches, implement and review each batch, review the integrated change, then execute the independent verification plan. Test code can be developed during implementation. A single review can cover both batch and overall scope for a single batch if the record says so.
+Provide material locations, the versions to adopt and relevant code locations. If only part of the material applies, identify that scope. Mention known gaps when materials are incomplete.
 
-Results identify the actual code/document version, scope, executor, environment and evidence. Review is not a runtime test. Missing accounts, tools or environments remain unexecuted checks with a concrete next action; they are not deleted to produce a passing report.
+The agent checks access and coverage of the delivery goal. When adopting an authoritative PRD or prototype, it preserves the originals and records the adopted scope, gaps and decisions in `scope.md`; scattered references instead inform authored requirements. Covered interactions are reused, with uncovered changes developed as needed. Follow the requirements document and its source links to see what was adopted and which decisions remain.
 
-A meaningful change gets one record explaining reason, old/new meaning, decision and affected work. Editable requirements/design/contracts/SQL/tests are updated, affected conclusions are reviewed, and old evidence remains historical. Unrelated work is not reset. An implementation defect is fixed against the requirement, not hidden by weakening it.
+### Changing a feature, fixing a defect or refactoring
 
-## Continue in another conversation
+Provide the relevant repository and feature location, expected behavior, current problems and behavior that must be preserved. For a defect, include available reproduction steps, errors or logs; for refactoring, explain the technical goal and external behavior that must remain unchanged.
 
-At a stable phase or batch boundary ask for a handoff to a new conversation. The agent saves state, current facts, unresolved changes and next-step references, then supplies a short prompt with the absolute delivery path. Open the new conversation yourself and explicitly resume Aimship there. A different host uses that same directory and state; do not copy the materials. It needs its own authorized access to the material and code roots.
+The agent examines the implementation, confirms requirements and technical constraints, and arranges design, implementation, review and verification. Ordinary debugging stays within the current work; a significant unknown requiring independent investigation leads to an arrangement change. `plan.md` tracks implementation, while `review.md` and `testing.md` record review and actual verification results.
 
-The new conversation reads that state and the needed current inputs. It does not need the entire chat, repeat agreed goals, or rerun every test. After compression it reloads missing rules and inputs using the saved binding. If the location is lost, provide the delivery path. Avoid concurrent writing sessions for the same delivery; independent deliveries can progress separately.
+In all these situations, the agent preserves the original request and maintains delivery records. Important business, scope, compatibility, cost or data decisions remain yours; routine technical decisions stay within your authorization. An unanswered decision is not treated as approval, and dependent work waits for resolution.
 
-If a referenced repository moved, give the new location; the agent checks identity before repairing it. Interrupted operations need inspection of actual artifacts before continuation, especially operations with side effects. A revision conflict is reconciled, never force-overwritten.
+<a id="review"></a>
+<a id="review-documents-and-continue"></a>
+## 3. Proceed and review
 
-## Update or stop using Aimship
+The usual development order is PRD/Scope → technical design → interfaces and independent SQL when applicable → test cases → implementation plan → implementation/review/verification → handoff and acceptance. Prototype, investigation and design-only work keep their agreed endpoint; review-only and verify-only reuse their existing basis.
 
-Use the single [installation guide](installation.md) for commands, host reload differences and troubleshooting.
+For each document requiring your review, the agent generates and self-checks it, provides a link, a short summary and the next stage, then waits for your review. Read the document and either request changes or explicitly approve it. Requested edits are revised, self-checked and presented again. Questions, silence and asking to see results do not count as approval.
 
-Explicitly install the desired local release/version using the same installer. Daily work uses fixed local files, not repeated `npx ...@latest` calls. Installation preserves customizations and delivery content, and reports conflicts with modified or unrelated skill files.
+Your explicit approval is recorded against that document version and automatically starts the next authorized stage; no second start confirmation is needed. If you have explicitly arranged to continue in a new session, the agent saves a handoff first; see [session arrangements](#continue). The chat shows the current stage, pending document, review status and next stage. Document approval is separate from final delivery acceptance.
 
-When a session's old rules differ from the current installation, finish saving current facts and switch at a stable point. Reload the new core/current stage, assess compatibility and adopt the new rules. If context cannot reliably refresh, resume the same delivery in a new conversation. Unknown formats remain read-only; unsupported migration is reported rather than guessed. Ended deliveries are not swept or rewritten during upgrade.
+Authorized implementation, agent reviews, defect repairs and retests can proceed continuously. Each implementation batch is reviewed, followed by overall review and independent verification. New material decisions and production actions still need authorization.
 
-Uninstall through the stable launcher as documented in [the CLI guide](cli.md). It removes only confirmed managed files, retaining delivery materials, custom content and necessary configuration. Removing delivery data is a separate explicit action.
+<a id="results"></a>
+<a id="3-inspect-progress-and-results"></a>
+## 4. Inspect progress and results
 
-## Decide when work is done
+Start with the delivery's **`status.md`** for the current stage, pending documents, review status, blockers, next stage and artifact links. Read verification conclusions alongside the tested version, environment and evidence. Checks lacking accounts, tools or environments remain blocked or unexecuted rather than passing.
 
-The endpoint controls completion. A design commission ends with its agreed design; development includes its required validation. Asking to see current results does not shorten the goal. An explicit decision to end earlier preserves the original goal and outstanding work in the handoff.
+<a id="delivery-structure"></a>
+### Delivery structure and documents
 
-Goal achieved, user acceptance, merge and deployment remain separate. Small later corrections can reopen the delivery while retaining its previous closure; a new goal or substantial redesign starts a related delivery. Aimship does not automatically manage parent/child work or multiple agents.
+By default, each request has its own delivery directory under `~/Aimship/`, while code stays in its existing repositories.
+
+The tree below lists delivery artifacts and their purposes. Files are generated according to the selected stages and input conditions; unselected stages produce no empty documents. `prd.md` and `scope.md` are alternative requirement entries, not two files required for every delivery.
+
+```text
+~/Aimship/
+├── 20261023-order-export/         # One request, one delivery folder
+│   ├── status.md                 # Generated overview and reading entry
+│   ├── prd.md                    # Authored requirements, scope and acceptance
+│   ├── scope.md                  # Used instead of PRD when adopting authoritative inputs
+│   ├── tech-design.md            # Architecture, changes, data, risks and requirement coverage
+│   ├── plan.md                   # Implementation batches, tasks and actual execution
+│   ├── testing.md                # Test cases, coverage, runs and retest results
+│   ├── review.md                 # Batch/overall reviews, findings and follow-up
+│   ├── handoff.md                # Delivered result, usage, validation and remaining work
+│   ├── diagnosis.md              # Only for an independent investigation
+│   ├── change-log.md             # Meaningful changes, decisions and affected work
+│   ├── openapi.yaml              # New HTTP contract; reuse an existing authority when available
+│   ├── database.sql              # SQL for one database; multiple targets use database-<id>.sql
+│   ├── prototype/                # Newly authored prototypes when required
+│   │   └── index.html            # Entry for an HTML prototype; its assets stay here
+│   ├── source/                   # Preserved original request and adopted input versions
+│   │   ├── request.md            # Original commission or source entry
+│   │   └── …                     # External PRD, prototype, screenshots and other inputs
+│   └── .aimship/                 # Managed state and supporting evidence
+│       ├── state.json            # Stages, references, versions and repository/worktree links
+│       ├── state.previous.json   # Previous state for recovery after writes
+│       ├── view.json             # Metadata for the generated status view
+│       └── evidence/             # Evidence retained when needed
+└── 20261024-another-request/      # Independent request and progress
+```
+
+Formal documents are directly in the request folder. `source/` preserves adopted originals; `.aimship/` holds internal records. The software itself is installed separately in `~/.aimship/`.
+
+Filenames, outlines and identifier rules come from shared templates. Requirements and acceptance criteria link to implementation tasks, reviews and versioned test cases/results. The [document reference](reference.md) explains exactly when each artifact is produced and what it contains.
+
+<a id="changes"></a>
+<a id="review-verify-and-change"></a>
+<a id="4-requirements-change-during-delivery"></a>
+## 5. Requirements change during delivery
+
+Explain what changed, why, and what should remain. If you edited a formal document, identify the location so the agent can reconcile its meaning.
+
+The agent assesses the impact on scope, design, implementation and verification, records decisions, and updates affected documents and work arrangements. It brings necessary tradeoffs to you while other authorized work continues. Adopted originals are preserved.
+
+A material change to an approved document returns it to review and holds dependent work until the review is resolved. Earlier approvals and results remain as history; an old approval cannot authorize the revised content. Work resumes in dependency order after re-review. Unaffected work is retained, and formatting or typo fixes do not require full re-review.
+
+Meaningful changes and their impact are recorded in `change-log.md`; see `status.md` for next steps. Do not edit `status.md` to change requirements or record acceptance: it is a generated view. Any manual edits need preserving before the agent reconciles and regenerates it.
+
+<a id="continue"></a>
+<a id="continue-in-another-conversation"></a>
+<a id="5-resume-after-a-pause-or-in-another-session"></a>
+<a id="6-resume-after-a-pause-or-in-another-session"></a>
+## 6. Session arrangements and continuing work
+
+### The maintainer's session practice
+
+To manage growing context, the maintainer has used the following arrangement of separate sessions (windows):
+
+| Work | Session arrangement |
+| --- | --- |
+| Requirements / Scope | One session |
+| Technical design, SQL and interface documents | One shared session |
+| Test-case design | One session |
+| Implementation plan | One session |
+| Implementation | One session per implementation batch, including that batch's agent review |
+| Overall review | One session |
+| Test execution | One session per test batch |
+
+This is practical experience, not a required split or a stage completion condition. Adjust it to the task's size, volume of materials and accumulated context. Assess any combined arrangement in actual use. Sharing a session for technical design, SQL and interfaces still requires the agreed document order: review technical design first, then each applicable interface/SQL document individually. A shared window does not bypass approval.
+
+Implementation batches and test batches serve different purposes. Test batches follow the verification arrangement and need not correspond one-to-one with implementation batches; this does not require testing after every implementation batch. A new window alone does not guarantee independent judgment or quality. Each new session still needs the relevant complete formal documents, saved state and actual artifacts, not just a brief chat summary.
+
+### Arrange the next session and hand off
+
+Aimship defines stages, artifacts, reviews and handoffs; it does not create new sessions. When changing windows, open a new session in your AI tool and provide the same delivery directory and handoff information.
+
+If you want to change sessions after approving a document, say so with the approval, for example: “This document is approved. Save the handoff first; I will continue in a new window.” The agent records approval and your continuation arrangement without starting the next stage in the current session. For implementation or test batches, you can instead say: “Finish this batch, save the results and handoff, and leave the next batch for a new session.” This does not add human approval requirements to execution records.
+
+Before ending the current session, have the agent save progress, review status, unresolved issues and the next step, and provide the full delivery directory path and relevant code locations. In the new session, select Aimship and provide the same delivery directory. The agent reads the relevant complete formal documents and state, checks actual artifacts and continues according to the saved arrangement. Ensure that a different tool can access the same materials and code.
+
+Keep only one writing session per delivery; the old session must stop writing before the new one takes over. Pending documents still require your explicit approval, and changing windows cannot bypass review. Progress and next steps remain in the same `status.md`; you do not need to copy the entire chat.
+
+### Handle interruptions and version changes
+
+After an unexpected interruption, have the agent check completed operations before repeating writes or other actions with side effects. If a repository moved, provide its new location so the agent can verify its identity and update the association. State conflicts or progress-view problems need reconciliation or repair, not forced overwrites.
+
+After a software upgrade, an old session may retain old rules. Save work, then have the agent reconcile the current version and delivery records at a stable boundary; start a new session if context cannot refresh reliably. Older delivery formats require explicit migration, rule adoption and document reconciliation before work continues; unknown formats remain read-only. Originals and historical results are preserved without inventing work that was never performed or treating old completion records as approval. The [CLI protocol](cli.md) provides recovery details for the agent.
+
+<a id="parallel"></a>
+<a id="work-on-two-requests-at-once"></a>
+<a id="6-progress-several-deliveries-at-once"></a>
+## 7. Progress several deliveries at once
+
+Use a separate delivery directory for each request, with one writing session per delivery. Tell the agent about known shared code, interfaces, databases or test environments.
+
+While one delivery changes code, another can perform read-only analysis. Before both change the same code, arrange sequential implementation or separate checkouts/worktrees, reusing existing isolation when available. The agent checks overlap against accessible known delivery records and documents coordination in the plan. Unknown or stale records and work outside Aimship limit this check.
+
+Read each delivery's own progress and results. Completing a branch does not complete integration; Aimship provides no global lock, automatic agent scheduling, automatic worktree creation or automatic merge.
+
+<a id="completion"></a>
+<a id="decide-when-work-is-done"></a>
+<a id="7-complete-a-delivery"></a>
+## 8. Complete a delivery
+
+Review artifact locations, usage instructions, review and verification conclusions, remaining issues and next steps in the handoff. Compare them with the original goal when deciding whether to accept the result.
+
+The agent records goal completion, user acceptance, merge and deployment separately. Asking for a preview does not shorten the goal; if you explicitly end early, the handoff preserves the original goal and unfinished work.
+
+Small later corrections can continue the same delivery while preserving its earlier completion record. A new goal or substantial redesign starts a related delivery.
+
+<a id="troubleshoot"></a>
+<a id="8-problems-during-use"></a>
+## 9. Problems during use
+
+| Situation | What to do |
+| --- | --- |
+| Materials or code cannot be accessed | Grant the required directory access in the current tool and identify the failed operation; do not move materials to bypass restrictions |
+| The progress page differs from actual results | Have the agent inspect current records and files, preserve manual edits and regenerate the progress page |
+| A formal document changed outside the session | Identify the changes and have the agent assess their meaning and effect on subsequent work |
+| An old delivery cannot continue | Have the agent check format migration, rule adoption and document reconciliation, preserving historical results and explaining blockers |
+| Aimship is missing, or installation/version problems occur | See [installation and upgrade problems](../README.md#installation-troubleshooting) in the README |
+
+For a bug report, include the tool and Aimship versions, the operation, expected and actual results, and minimal reproducible materials. Redact credentials, personal paths and business data before submitting to [GitHub Issues](https://github.com/clsx/aimship/issues).
+
+## Related references
+
+<a id="artifacts"></a>
+<a id="keep-only-useful-artifacts"></a>
+See the [delivery document reference](reference.md) for generation conditions, stage outputs, outlines and identifier rules. The agent maintains these as work progresses; you do not need to learn them all before starting.
+
+<a id="update"></a>
+<a id="update-or-stop-using-aimship"></a>
+For software upgrades, adding tools, version queries and installation health checks, see the [README](../README.md#update).
+
+<a id="uninstall"></a>
+For tool disconnection or full uninstallation, see the [README](../README.md#uninstall). Source development and isolated validation belong in [Contributing](../CONTRIBUTING.md).

package/docs/guide.zh-CN.md

@@ -0,0 +1,210 @@
+# Aimship 使用指南
+
+[English](guide.md) · [README](../README.zh-CN.md)
+
+本指南按实际使用场景说明：需要提供什么，Agent 如何推进，以及在哪里查看成果。你不需要记住阶段名称或固定提示词。
+
+<a id="install"></a>
+尚未安装时，先阅读 README 的[安装说明](../README.zh-CN.md#install)。
+
+[选择 Aimship](#hosts) · [按当前情况开始](#start) · [推进与审核](#review) · [查看进度与成果](#results) · [需求变化](#changes) · [会话与续接](#continue) · [并行需求](#parallel) · [完成交付](#completion) · [使用问题](#troubleshoot)
+
+<a id="hosts"></a>
+<a id="1-在宿主中选择-aimship"></a>
+<a id="1-在-ai-开发工具中选择-aimship"></a>
+## 1. 在 AI 工具中选择 Aimship
+
+安装后开启新的 AI 工具会话，选择 Aimship：
+
+| AI 工具 | 如何选择 | 未显示时 |
+| --- | --- | --- |
+| Codex | 在 Skill 选择器中选择 Aimship；CLI 中使用 `$aimship` | 新建会话或重启 CLI，列表未刷新时重启应用 |
+| Cursor | 使用 `/aimship` | 新建 Agent 会话，检查 Customize → Skills；列表未刷新时重启 Cursor |
+| Claude Code | 使用 `/aimship` | 新建会话并检查斜杠命令列表；列表未刷新时重启 Claude Code |
+
+每个 AI 工具分别需要登录、可用模型以及交付资料和相关代码仓库的访问权限，在实际操作需要时授权。交付资料单独保存，代码仍在原仓库中。
+
+AI 工具集成仍处于实验阶段，真实 Skill 发现、目录访问和跨工具接续仍待验证。安装文件健康不等于 AI 工具已加载 Skill。Codex 和 Cursor 共用入口，兼容 AI 工具也可能发现其他位置的入口；出现重复项时检查路径和版本，保留无关或定制内容。AI 工具行为可参考官方 [Cursor 文档](https://cursor.com/docs/skills)和 [Codex Skill 位置说明](https://learn.chatgpt.com/docs/build-skills)。
+
+<a id="start"></a>
+<a id="describe-the-work-and-its-endpoint"></a>
+## 2. 按当前情况开始
+
+### 从一个想法开始
+
+说明想解决的问题、使用者、期望变化和已知限制。有截图、讨论记录或参考资料时一起提供，无需先准备完整 PRD。
+
+Agent 会澄清影响范围和验收判断的缺口，整理需求，提出所需阶段及执行顺序。你确认目标和重要取舍后，Agent 继续推进。需求与验收标准通常记录在 `prd.md`，当前进度从 `status.md` 查看。
+
+### 已有 PRD、原型或其他资料
+
+提供资料位置、准备采用的版本，以及相关代码位置；如果只采用部分内容，说明本次范围。已有资料不完整时，可以直接说明已知缺口。
+
+Agent 会核对资料是否可访问、是否覆盖本次目标。采用权威 PRD／原型时，保留原件，通过 `scope.md` 记录采用范围、缺口和决定；零散参考则用于编写需求。已有交互被充分覆盖时复用，未覆盖的变化再补充。你可从需求文档和关联资料中查看采用了哪些内容、还需决定什么。
+
+### 修改现有功能、修复缺陷或重构
+
+提供相关仓库和功能位置，说明期望行为、当前问题及必须保留的行为。修复缺陷时附上可用的复现条件、错误信息或日志；重构时说明技术目标和不能改变的外部行为。
+
+Agent 会检查相关实现，确认需求与技术约束，安排设计、实施、审核和验证。普通调试随当前工作处理；重大未知问题需要独立调查时，再调整安排。`plan.md` 记录实施进度，`review.md` 和 `testing.md` 分别记录审核与实际验证结果。
+
+以上场景都由 Agent 保留原始委托并维护交付记录。重要的业务、范围、兼容性、成本或数据决策由你决定；授权内的日常技术取舍由 Agent 处理。待决问题没有回应时不会被视为批准，相关依赖工作等待解决。
+
+<a id="review"></a>
+<a id="逐份审核与自动衔接"></a>
+## 3. 推进与审核
+
+通常的开发顺序是 PRD／Scope → 技术方案 → 接口和独立 SQL（适用时）→ 测试用例 → 实施计划 → 实施／评审／验证 → 交付验收。原型、调查和仅设计委托保留约定终点；仅 review、仅 verify 使用已有依据。
+
+每份需人审文档生成、自检后，Agent 给出文档入口、短摘要和下一阶段，等待你审核。你阅读文档后提出修改意见，或明确表示通过。有修改意见时，Agent 修改、自检后再次送审。提问、沉默和要求看结果都不算批准。
+
+你明确通过后，批准会关联该文档版本，Agent 自动开始下一授权阶段，不再询问是否开始。如果你已明确安排换会话继续，Agent 会先保存交接信息，具体见[会话安排](#continue)。聊天中会显示当前阶段、待审文档、审核状态和下一阶段。文档批准与最终交付验收分开。
+
+授权内的实施、Agent 评审、缺陷修复和复测可连续推进。实施按批次审核，全部完成后整体审核，再独立验证。新增实质决定和生产动作仍需对应授权。
+
+<a id="results"></a>
+<a id="3-查看进度与成果"></a>
+## 4. 查看进度与成果
+
+从交付目录的 **`status.md`** 查看当前阶段、待审文档、审核状态、阻塞事项、下一阶段和成果入口。查看验证结论时，同时关注对应版本、环境和证据。缺少账号、工具或环境的检查会标为阻塞或未执行，不能计为通过。
+
+<a id="delivery-structure"></a>
+### 交付目录与文档
+
+默认每个需求在 `~/Aimship/` 下使用独立交付目录，代码保留在原仓库。
+
+下方列出交付产物及其用途；实际生成范围由所选阶段和输入条件确定，未选阶段不生成空文档。`prd.md` 与 `scope.md` 是需求入口的两种选择，并非每个需求都要同时生成。
+
+```text
+~/Aimship/
+├── 20261023-订单导出/             # 每个需求一个独立交付目录
+│   ├── status.md                 # 自动生成的进度总览和阅读入口
+│   ├── prd.md                    # 自编需求：目标、范围、需求和验收标准
+│   ├── scope.md                  # 采用权威外部资料时使用，替代自编 PRD
+│   ├── tech-design.md            # 技术方案：架构、改动、数据、风险和需求覆盖
+│   ├── plan.md                   # 实施计划：批次、任务及实际执行记录
+│   ├── testing.md                # 测试用例、覆盖关系、执行与重测结果
+│   ├── review.md                 # 各批及整体审核、发现的问题和处理结论
+│   ├── handoff.md                # 交付结果、使用方式、验证结论和遗留事项
+│   ├── diagnosis.md              # 仅独立调查时生成的定位与证据记录
+│   ├── change-log.md             # 重要变更、决定及受影响的工作
+│   ├── openapi.yaml              # 新建 HTTP 契约；已有权威契约优先复用
+│   ├── database.sql              # 单数据库 SQL；多目标为 database-<id>.sql
+│   ├── prototype/                # 符合生成条件时新建的原型
+│   │   └── index.html            # HTML 原型入口，相关资源也放在此目录
+│   ├── source/                   # 保留原始需求和采用的外部资料版本
+│   │   ├── request.md            # 原始委托或来源入口
+│   │   └── …                     # 外部 PRD、原型、截图及其他输入
+│   └── .aimship/                 # 工具维护的内部状态与辅助证据
+│       ├── state.json            # 阶段、引用、版本及仓库／worktree 关联
+│       ├── state.previous.json   # 写入后用于恢复的上一版状态
+│       ├── view.json             # 进度视图的生成元信息
+│       └── evidence/             # 按需保留的验证等证据
+└── 20261024-另一个需求/           # 独立的资料与进度
+```
+
+正式文档直接放在需求目录下；`source/` 保留采用的原件，`.aimship/` 保存内部记录。软件安装目录为 `~/.aimship/`，与各需求目录内的 `.aimship/` 分别管理。
+
+文档名称、大纲和编号遵循统一模板。需求与验收标准关联到实施任务、审核、带版本的测试用例及执行结果。[交付文档参考](reference.zh-CN.md)进一步说明每种文档的生成条件和具体内容。
+
+<a id="changes"></a>
+<a id="review-verify-and-change"></a>
+<a id="4-推进中需求发生变化"></a>
+## 5. 推进中需求发生变化
+
+说明发生了什么变化、原因以及希望保留的内容。如果已修改正式文档，指出位置，让 Agent 核对修改的含义。
+
+Agent 会分析对范围、设计、实现和验证的影响，记录决定，更新受影响的工作安排和文档。需要你判断的取舍会提出，其他授权内工作继续，原始采用资料继续保留。
+
+已批准文档发生实质变更时，回到对应阶段重审，依赖它的工作等待审核解决后再继续；旧批准和结果保留为历史，不能用旧批准放行新版。重审通过后，按依赖顺序恢复。无关工作不重置，排版和错字修正不需全量重审。
+
+重要变化及影响记录在 `change-log.md`，后续安排从 `status.md` 查看。不要通过修改 `status.md` 来改变需求或表示验收；它是生成视图，已有手改内容需先保留，再由 Agent 核对和重建。
+
+<a id="continue"></a>
+<a id="continue-in-another-conversation"></a>
+<a id="5-暂停后或换会话继续"></a>
+<a id="6-暂停后或换会话继续"></a>
+## 6. 会话安排与继续工作
+
+### 维护者的分窗口实践
+
+为了控制上下文不断累积带来的负担，维护者实际使用过以下会话（窗口）安排：
+
+| 工作内容 | 窗口安排 |
+| --- | --- |
+| 需求／Scope | 一个窗口 |
+| 技术文档、SQL、接口文档 | 共用一个窗口 |
+| 测试用例设计 | 一个窗口 |
+| 实施计划 | 一个窗口 |
+| 实施 | 每个实施批次一个窗口，包含该批 Agent 评审 |
+| 整体 review | 一个窗口 |
+| 测试执行 | 每个测试批次一个窗口 |
+
+这是使用经验，不是强制分窗规则或阶段完成条件。可按任务规模、资料量和上下文累积情况调整；合并后的效果需在实际工作中核对。技术文档、SQL 和接口共用窗口时，仍按既定顺序先审技术文档，再逐份审核适用的接口／SQL 文档，不能因为共用窗口而跳过审核。
+
+实施批次与测试批次承担不同工作。测试批次按验证安排划分，不要求与实施批次一一对应，也不要求每个实施批次结束后立即测试。新窗口本身不保证判断独立或质量；每个新会话仍需读取相关的完整正式文档、已保存状态和实际成果，不能只靠简短聊天摘要接手。
+
+### 安排新会话与交接
+
+Aimship 负责阶段、产物、审核与交接规范，本身不创建新会话。需要换窗口时，由你在所用的 AI 工具中开启新会话，再提供同一交付目录和交接信息。
+
+如果希望文档通过后换窗口，在批准时一并说明，例如：“这份文档通过。先保存交接信息，我会在新窗口继续。”Agent 会记录批准和你的续接安排，不在当前会话直接开始下一阶段。实施或测试批次则可以说：“完成本批，保存结果和交接信息，下一批在新会话继续。”这不增加对执行记录的人工审批要求。
+
+结束当前会话前，请 Agent 保存进度、审核状态、未解决问题和下一步，并给出交付目录的完整路径及相关代码位置。新会话中选择 Aimship，提供同一个交付目录；Agent 读取相关的完整正式文档和状态、核对实际成果后，按已保存的安排继续。更换 AI 工具时也要确保能访问同一份资料和代码。
+
+同一交付只保留一个写入会话，旧会话停止写入后再由新会话接手。待审文档仍需你明确通过，换窗口不能跳过审核。进度和下一步仍从同一份 `status.md` 查看，无需复制完整聊天。
+
+### 处理中断与版本变化
+
+意外中断时，让 Agent 先核对已经完成的操作，避免重复写入或重跑有副作用的动作。代码仓库搬迁后提供新位置，由 Agent 核对身份后更新关联。状态冲突或进度视图异常需要先协调或修复，不能强行覆盖。
+
+软件升级后，旧会话可能保留旧规则。先保存工作，再让 Agent 在稳定边界核对当前版本与交付记录；无法可靠刷新时开启新会话。旧格式交付需要明确迁移、采用规则并整理相关文档后继续，未知格式保持只读。已有原件和历史结果保留，不补造过去未执行的工作，也不将旧完成记录当作批准；恢复协议供 Agent 查阅 [CLI 文档](cli.md)。
+
+<a id="parallel"></a>
+<a id="work-on-two-requests-at-once"></a>
+<a id="6-同时推进多个需求"></a>
+## 7. 同时推进多个需求
+
+不同需求使用独立交付目录，每个交付只保留一个写入会话。向 Agent 说明已知的共享代码、接口、数据库或测试环境。
+
+一个需求正在修改代码时，另一个可以先做只读分析。两个需求都要修改同一份代码之前，安排串行实施或独立 checkout／worktree，并优先复用已有隔离。Agent 会根据可访问的已知交付记录核对重叠范围，在计划中记录协调方式；未知或过期记录、Aimship 外的工作不在完整掌握范围内。
+
+各需求分别查看自己的进度和结果。分支完成不代表集成完成；Aimship 不提供全局锁、自动 Agent 调度、自动创建 worktree 或自动合并。
+
+<a id="completion"></a>
+<a id="decide-when-work-is-done"></a>
+<a id="7-完成交付"></a>
+## 8. 完成交付
+
+查看交接记录中的成果位置、使用方式、审核和验证结论、遗留问题与后续事项，并对照原目标判断是否接受。
+
+Agent 会分别记录目标完成、用户验收、合并和部署的实际情况。要求预览不代表缩短目标；明确提前结束时，交接中保留原目标和未完成工作。
+
+后续小修正可以继续原交付，并保留此前完成记录；新目标或大幅重新设计则建立关联的新交付。
+
+<a id="troubleshoot"></a>
+<a id="8-使用中遇到问题"></a>
+## 9. 使用中遇到问题
+
+| 情况 | 如何处理 |
+| --- | --- |
+| 无法访问资料或代码 | 在当前 AI 工具授权需要的目录，说明失败的具体操作，不通过搬动资料绕过权限限制 |
+| 进度页与实际成果不一致 | 请 Agent 核对当前记录和实际文件，保留手改内容后重建进度页 |
+| 正式文档在会话外被修改 | 指出修改位置，请 Agent 核对含义及对后续工作的影响 |
+| 旧交付无法继续 | 请 Agent 检查格式迁移、规则采用和文档整理，保留历史结果并说明阻塞原因 |
+| 找不到 Aimship、安装或版本异常 | 查看 README 的[安装与升级问题](../README.zh-CN.md#installation-troubleshooting) |
+
+反馈问题时提供 AI 工具和 Aimship 版本、具体操作、预期与实际结果，以及可复现的最小资料；隐去凭据、个人路径和业务数据，通过 [GitHub Issues](https://github.com/clsx/aimship/issues)提交。
+
+## 相关参考
+
+<a id="artifacts"></a>
+<a id="keep-only-useful-artifacts"></a>
+文档生成条件、阶段产物、大纲与编号规则见[交付文档参考](reference.zh-CN.md)。这些规则由 Agent 随工作维护，无需在开始前逐项掌握。
+
+<a id="update"></a>
+<a id="update-or-stop-using-aimship"></a>
+软件升级、添加 AI 工具和版本／安装状态查询见 [README](../README.zh-CN.md#update)。
+
+<a id="uninstall"></a>
+断开 AI 工具或完整卸载见 [README](../README.zh-CN.md#uninstall)。源码开发与隔离验证见[贡献指南](../CONTRIBUTING.md)。