aimship 0.1.0-preview.11 → 0.1.0-preview.13

package/docs/guide.md

@@ -2,242 +2,408 @@
 
 [中文](guide.zh-CN.md) · [README](../README.md)
 
-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.
+[Delivery directory](#delivery-structure) · [1. Usage example](#start) · [2. Sessions and continuation](#guide-sessions) · [3. Requirements inputs and changes](#guide-inputs) · [4. Code and multiple deliveries](#guide-projects) · [5. Troubleshooting and maintenance](#troubleshoot)
 
-<a id="install"></a>
-If Aimship is not installed yet, start with the README's [installation instructions](../README.md#install).
+<a id="24-check-current-work"></a>
+<a id="44-delivery-structure-and-documents"></a>
+<a id="results"></a>
+<a id="3-inspect-progress-and-results"></a>
+<a id="4-inspect-progress-and-results"></a>
+<a id="4-inspect-progress-and-accept-results"></a>
+<a id="check-current-work"></a>
+<a id="artifacts"></a>
+<a id="keep-only-useful-artifacts"></a>
+<a id="related-references"></a>
+<a id="appendix-sql-and-engineering-versions"></a>
+<a id="document-details"></a>
+<a id="sql-changes-and-progress"></a>
+<a id="sql-and-engineering-versions"></a>
+<a id="delivery-structure"></a>
+<a id="stage-outputs-and-content"></a>
+<a id="delivery-structure-and-documents"></a>
+<a id="fixed-outlines-and-traceable-identifiers"></a>
+<a id="guide-directory"></a>
 
-[Select Aimship](#hosts) · [Start in different scenarios](#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)
+## Delivery directory at a glance
 
-<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
+The default materials root is `~/Aimship/` under your home directory, unless installation configured another location. **Each delivery has its own directory under that root; use the actual path in the AI’s receipt.** Explicitly state a different save location if needed.
 
-After installation, open a new tool session and select Aimship:
+Carry out the delivery in your AI tool workspace, with access to both existing materials and the Aimship delivery directory:
 
-| 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 |
+```text
+AI tool workspace
+├── Existing user project materials (supply as applicable; keep in place)
+│   ├── Prototypes, PRDs and other reference documents (if available)
+│   └── Project code (if available)
+└── This request’s delivery directory, created by Aimship initialization
+    └── Add original directory → ~/Aimship/20261027-login-signup/
+```
+
+[Activate Aimship and state the request](#guide-setup) below. Once initialization reports the actual path, add that delivery folder (`20261027-login-signup` in this example) to the current AI tool workspace, or grant access to it, then continue the delivery in this workspace. Provide access to existing project materials as needed; Aimship initialization does not create them. The directory name is only an example: do not create it manually in advance, copy the whole delivery, or create another set in the workspace.
 
-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.
+The delivery directory contains these materials:
+
+```text
+~/Aimship/                         # Materials root
+└── 20261027-login-signup/          # Example delivery directory
+    ├── status.md                  # Current work, pending reviews, next action
+    ├── source/request.md          # Original request
+    ├── prd.md                     # Requirements and acceptance criteria
+    ├── prototype/index.html       # Page interaction prototype
+    ├── tech-design.md             # Technical design
+    ├── openapi.yaml               # HTTP interface contract
+    ├── database.sql               # This example's single-database changes
+    ├── testing.md                 # Cases and later execution results
+    ├── plan.md                    # Implementation tasks and progress
+    ├── review.md                  # Batch and overall reviews
+    └── handoff.md                 # Results and handoff instructions
+```
 
-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.
+Materials develop gradually and are kept as needed. Search readable REQ, AC and TC numbers across documents; corresponding numbers stay consistent without requiring anchor links. `scope.md` adopts authoritative external requirements, `change-log.md` records important changes, and `diagnosis.md` is for standalone investigations. Open `status.md` for progress; tell the AI directly about requirement changes or acceptance decisions.
 
+<a id="1-start-and-proceed"></a>
 <a id="start"></a>
 <a id="choose-the-requirement-authority"></a>
 <a id="describe-the-work-and-its-endpoint"></a>
-## 2. Start in different scenarios
+<a id="2-start-in-different-scenarios"></a>
+<a id="1-first-use"></a>
+<a id="guide-example"></a>
+<a id="1-sign-up-and-login-a-delivery-example"></a>
+
+<a id="1-aimship-delivery-walkthrough"></a>
+
+## 1. Aimship usage example
+
+Follow sign-up and login from requirements to acceptance. **This is fictional practice; wording and business choices need not be copied.** The example later supplies a project and isolated test database, with prototype review after requirements and before technical design. Actual prototype placement follows the delivery's needs.
+
+Use one Aimship entry within a session, then continue after approval as arranged; no invocation is needed at every stage. When your review is required, the AI presents one item at a time and waits for a clear decision. Revisions return for review.
+
+<a id="11-prepare-a-workspace"></a>
+<a id="12-activate-aimship-and-describe-the-request"></a>
+<a id="13-check-the-saved-result-and-answer-necessary-questions"></a>
+<a id="prepare-a-workspace"></a>
+<a id="hosts"></a>
+<a id="1-select-aimship-in-your-host"></a>
+<a id="1-select-aimship-in-your-ai-development-tool"></a>
+<a id="1-select-aimship-in-your-ai-tool"></a>
+<a id="activate-aimship-and-describe-the-request"></a>
+<a id="check-the-saved-result-and-answer-necessary-questions"></a>
+<a id="install"></a>
+<a id="starting-without-a-requirements-document"></a>
+<a id="guide-setup"></a>
 
-After explicit activation, a concrete problem or intended change is enough to start. The agent preserves relevant original wording and visible discussion, checks whether this is a new or existing delivery, and reuses the current accessible workspace. If access is missing, it names the materials path and the operation you need to complete. Code can wait; a project name is not proof of access.
+### 1.1 Activate Aimship and state the request
 
-Initialization saves `source/request.md`, structured state and the generated `status.md`. Its receipt states what was saved, where, the bound Aimship version, code association, current work and next step. PRD/Scope is created when substantive requirements are drafted. Unknown endpoint, interaction, interface or database conditions remain unknown; “requirements first” does not mean “requirements only” or permission to implement.
+**User actions:** Explicitly request Aimship and state the goal. For example:
 
-To adopt an ongoing conversation, explicitly ask to use Aimship for the discussed request. The agent uses visible relevant input and identifies missing history, without asking known questions again or converting suggestions into decisions. If access preparation requires a new session before saving, take the provided unsaved context and intended location with you, then explicitly activate Aimship again.
+> Use Aimship for username/password sign-up, login, logout and a home page requiring login. Complete development and local verification, without deployment; I will supply code later.
 
-When code is ready, supply the accessible local checkout. The agent reads necessary instructions and engineering facts and associates it with the same delivery. It may read code during requirements if a conclusion depends on existing behavior. Association does not clone, move or modify code or grant implementation permission. New facts use the existing change process.
+For existing prototypes, PRDs or other documents, supply their original locations; originals stay in place and you need not copy them manually. Following the source rules, the AI retains copies of the formally adopted versions and necessary dependencies under this delivery's `source/` and records the adoption basis. Materials consulted only as background need not be copied in full. Before later revisions, identify the editable artifact; new versions do not overwrite earlier evidence.
 
-Repeated activation resumes the same identity and review stop. If a receipt is interrupted or the progress view fails, the agent checks what actually saved and repairs the missing view without recreating the delivery or overwriting materials. Ambiguous ownership is clarified. See [continuation](#continue) for the same steps in a new session; a passing mention of Aimship does not activate it.
+**AI processing:** Determines the delivery directory and checks access, preserves the request, creates or resumes the delivery, and reports the actual saved directory, current work and next action. If access is unavailable, it asks you to add that directory or grant access; it does not relocate the delivery into the workspace.
 
-### Starting without a requirements document
+**Outputs:** `source/request.md` preserves your words; `status.md` shows progress. For a new delivery, the AI saves your preferred language, or otherwise the language of the current conversation. Status and new documents use that language; filenames, IDs, original sources and existing documents remain unchanged.
 
-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.
+<a id="14-read-the-document-and-give-a-decision"></a>
+<a id="15-continue-after-approval"></a>
+<a id="review"></a>
+<a id="review-documents-and-continue"></a>
+<a id="3-proceed-and-review"></a>
+<a id="2-review-and-proceed"></a>
+<a id="read-the-document-and-give-a-decision"></a>
+<a id="continue-after-approval"></a>
+<a id="guide-requirements"></a>
+<a id="guide-prototype"></a>
+<a id="12-review-requirements-and-acceptance-criteria"></a>
+<a id="13-review-pages-and-interaction"></a>
 
-After initialization, the agent clarifies gaps in the goal, scope and acceptance criteria, organizes the requirements and acceptance criteria, and explains the work ahead. 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.
+### 1.2 Confirm requirements
 
-### Working from an existing PRD, prototype or other materials
+**User actions:** Supply the input you have.
 
-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.
+- No PRD/prototype: describe features and expected behavior, such as “Usernames must be unique; after logout, the home page must require login again.”
+- Existing materials: provide the PRD/prototype location, version and adopted scope. Say what is available even if it is incomplete.
 
-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.
+Open the presented requirements document and applicable prototype separately. Check scope, acceptance criteria and page behavior; approve the current item or identify what needs changing.
 
-### Changing a feature, fixing a defect or refactoring
+**AI processing:** Clarifies gaps, preserves authoritative external originals and reuses sufficient prototype coverage. Without materials, it writes requirements first, then creates the needed prototype after approval in this example's arrangement. No interaction change means no new prototype. It self-checks, submits, records approval and continues one item at a time.
 
-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.
+**Outputs:** `prd.md` states requirements and acceptance criteria, or `scope.md` records the adopted scope. This example creates `prototype/index.html` for pages and feedback states. A prototype is not implemented authentication; interaction checks not performed remain unverified.
 
-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.
+<a id="guide-session-example"></a>
 
-Preserve adopted versions of external material; a URL alone may not retain a version, and access gaps must be explicit. An existing editable PRD may be reused when you explicitly commission its maintenance and it fully states this scope, authorization and endpoint. Earlier authorship alone does not permit changing an adopted original.
+**New-session example:** After this example's requirements and prototype are approved and saved, stop writing in the old session and explicitly activate Aimship in a new one:
 
-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.
+> Use Aimship to continue the sign-up and login delivery at “actual delivery directory.” First read its state, approved materials and pending reviews.
 
-<a id="review"></a>
-<a id="review-documents-and-continue"></a>
-## 3. Proceed and review
+The AI rechecks access to the same delivery directory, reads its state and confirms technical design as next. If reviews remain pending, it stops there, without reinitializing or asking you to repeat all background. Staying in the original session is also fine.
 
-The standard sequence is requirements and acceptance criteria → technical design with applicable interface/SQL/interaction artifacts → test cases → implementation plan → implementation batches with batch review → overall review → verification → delivery acceptance. The agent organizes this sequence without asking you to select every core stage. Unrelated artifacts are not created; existing formal material is inspected before adoption, which does not itself constitute approval.
+<a id="guide-design"></a>
+<a id="14-review-the-technical-design"></a>
 
-After drafting and self-checking each document that needs your review, the agent shows the current stage status, document entry and review focus. Explicitly approve it or raise questions. Discussion, silence and requests to see results are not approval; revisions are self-checked and presented again. No next-stage continuation prompt is issued while review is pending.
+### 1.3 Review the technical design
 
-After explicit approval, the agent records the decision and document version, saves progress and next work, checks the save result, and then suggests the next action in the same handling of your message. You need not separately confirm saving or the prompt; failed saves are reported honestly. Within a suggested session group, the next item starts directly. At a group boundary, the agent suggests a new session and provides a short entry without executing the next group in that response. Say “continue in this session” to proceed without another approval. See [session grouping suggestions](#continue).
+**User actions:** Supply the project location and known test conditions. Open the design, check password protection, login state, access control and data changes, then approve or give feedback.
 
-If you explicitly exclude test cases and testing, the agent explains and records that scope once, completes the authorized development and review, and hands over an **untested partial result**. It does not quietly add excluded work or repeatedly persuade you. Finishing that scope is not standard complete delivery or a passing verification result. Document approval remains separate from final delivery acceptance.
+**AI processing:** Reads the project, checks technical conditions and designs the implementation and risk handling. It resolves missing essential facts and prepares interfaces/SQL after design approval.
 
-Authorized implementation, batch checks/repairs and retests can proceed. Review or test findings first lead to repairs or the existing change flow. New material decisions and production actions still need their corresponding authorization.
+**Outputs:** `tech-design.md` explains the implementation and tradeoffs. It plans later SQL; finished SQL is not required at this point.
 
-<a id="results"></a>
-<a id="3-inspect-progress-and-results"></a>
-## 4. Inspect progress and results
+<a id="guide-contracts"></a>
+<a id="15-review-interface-and-sql-documents-individually"></a>
 
-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.
+### 1.4 Review interface and SQL documents individually
 
-<a id="delivery-structure"></a>
-<a id="stage-outputs-and-content"></a>
-### Delivery structure and documents
+**User actions:** For the interface review, check requests, responses, errors and authentication. For SQL, check the target database, structure, change order and execution conditions. Approve or request changes separately.
 
-By default, each request has its own delivery directory under `~/Aimship/`, while code stays in its existing repositories.
+**AI processing:** Prepares applicable documents from the approved design, self-checks each and waits for review. Test design follows their approval. Existing authoritative contracts are reused; no relevant change means no file, and multiple databases have separate SQL.
 
-The tree below lists delivery artifacts and their purposes. Files follow the agreed delivery scope and actual artifact conditions; unrelated work produces no empty documents. `prd.md` and `scope.md` are alternative requirement entries, not two files required for every delivery.
+**Outputs:** This example's `openapi.yaml` defines HTTP interfaces; `database.sql` describes single-database changes. **Document approval does not authorize SQL execution or changes to migration mechanisms.**
 
-```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
-```
+<a id="guide-cases"></a>
+<a id="16-review-test-cases"></a>
 
-Formal documents are directly in the request folder. `source/` preserves adopted originals; `.aimship/` holds internal records. The software itself is installed separately in `~/.aimship/`.
+### 1.5 Review test cases
 
-<a id="fixed-outlines-and-traceable-identifiers"></a>
-The agent maintains links between requirements, acceptance criteria, implementation tasks, reviews and test results for traceability.
+**User actions:** Open the cases and check expected outcomes for normal sign-up/login, duplicate usernames, incorrect passwords, unauthenticated access and access after logout. Approve or identify gaps.
 
-<a id="changes"></a>
-<a id="review-verify-and-change"></a>
-<a id="4-requirements-change-during-delivery"></a>
-## 5. Requirements change during delivery
+**AI processing:** Turns acceptance criteria into checkable cases, with environment and coverage details. It prepares the implementation plan after case approval.
+
+**Outputs:** The cases section of `testing.md`. Test execution results do not exist yet.
+
+<a id="guide-plan"></a>
+<a id="17-review-the-implementation-plan"></a>
+
+### 1.6 Review the implementation plan
+
+**User actions:** Open the plan, check scope, dependencies, batches and verification arrangements, then approve or give feedback.
+
+**AI processing:** Splits tasks by engineering dependencies, such as authentication/session work before pages and access control, including test code and reviews. Implementation waits for the plan and required document approvals; even one batch needs a plan.
+
+**Outputs:** `plan.md` explains each batch's work, dependencies and checks.
+
+<a id="guide-implement"></a>
+<a id="18-implement-batches-and-review-each-batch"></a>
+
+### 1.7 Implement batches and review each batch
 
-Explain what changed, why, and what should remain. If you edited a formal document, identify the location so the agent can reconcile its meaning.
+**User actions:** Inspect changes and progress; point out deviations, such as “The post-sign-up redirect differs from the prototype.” No line-by-line approval of execution logs is needed.
 
-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.
+**AI processing:** Implements the plan, reviews each batch and resolves blocking issues before the next. After all batches, it performs the overall review before verification. Requirement changes return to the relevant review.
 
-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.
+**Outputs:** Project code, execution progress appended to `plan.md`, and batch findings and repairs in `review.md`.
 
-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="guide-overall"></a>
+<a id="19-review-the-complete-change"></a>
 
+### 1.8 Review the complete change
+
+**User actions:** Read the overall findings and remaining issues, pointing out omissions if needed. Each review entry does not need a separate document approval.
+
+**AI processing:** Checks all actual changes and connections across sign-up, login, logout and home-page access. It resolves issues blocking independent verification. A single-batch review can explicitly cover both batch and overall scope.
+
+**Outputs:** Overall conclusions appended to `review.md`. Code review does not replace running tests.
+
+<a id="guide-verify"></a>
+<a id="110-run-verification-and-handle-failures"></a>
+
+### 1.9 Run verification and handle failures
+
+**User actions:** Provide the agreed isolated test environment, read execution results and supply reproduction details or missing conditions. Separately authorized operations need an explicit target and action.
+
+**AI processing:** Runs cases against reviewed code, distinguishing passed, failed and unexecuted checks. It reviews fixes and retests while retaining failure history; requirement/design issues return to the relevant materials.
+
+**Outputs:** Actual code, environment, results and evidence appended to the same `testing.md`. Missing necessary verification is reported, not marked passed.
+
+<a id="25-accept-the-delivered-result"></a>
+<a id="completion"></a>
+<a id="decide-when-work-is-done"></a>
+<a id="7-complete-a-delivery"></a>
+<a id="8-complete-a-delivery"></a>
+<a id="accept-the-delivered-result"></a>
+<a id="guide-handoff"></a>
+<a id="111-inspect-and-accept-the-result"></a>
+
+### 1.10 Inspect and accept the result
+
+**User actions:** Follow the handoff instructions to inspect the feature. Explicitly accept it when it meets the goal, or describe actual versus expected behavior.
+
+**AI processing:** Summarizes results and remaining work, and records your actual acceptance decision. Complete delivery needs evidence of required document approvals, batch/overall review, independent verification and final acceptance.
+
+**Outputs:** `handoff.md` provides result locations, usage, verification conclusions and merge/deployment status. Earlier document approvals do not replace acceptance, and completed development does not mean deployed.
+
+<a id="guide-sessions"></a>
+
+## 2. Sessions and continuation
+
+<a id="2-sessions-progress-and-acceptance"></a>
+<a id="21-resume-in-a-new-session"></a>
+<a id="23-session-grouping-suggestions"></a>
 <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
+<a id="6-session-arrangements-and-continuing-work"></a>
+<a id="continuing-an-existing-delivery-or-switching-sessions"></a>
+<a id="3-continue-next-time"></a>
+<a id="arrange-the-next-session-and-hand-off"></a>
+<a id="resume-in-a-new-session"></a>
+<a id="session-grouping-suggestions"></a>
+<a id="guide-continue"></a>
+<a id="21-switch-sessions-and-resume"></a>
 
-### Session grouping suggestions
+### 2.1 When to switch sessions
 
-The following arrangement is based on experience from actual projects and can be adjusted to task size. At delivery creation or requirements confirmation, the agent records applicable suggested groups in state and shows them in `status.md`:
+Follow suggestions in `status.md` between requirements, technical design/applicable contracts, cases, plan, implementation batches, overall review and verification batches, or stay in the same session. Grouping does not change individual document reviews.
 
-| 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 |
+See the [new-session example](#guide-session-example). Keep one writing session per delivery. Trusted records can locate it directly; missing or ambiguous matches prompt clarification. The saved delivery language carries over. If switching before the first save, carry the unsaved request, intended location and pending operations.
 
-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 session does not bypass approval.
+<a id="22-continue-after-work-stops-unexpectedly"></a>
+<a id="continue-after-work-stops-unexpectedly"></a>
+<a id="guide-recovery"></a>
+<a id="32-interruptions-repeated-activation-or-inconsistent-progress"></a>
 
-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 session 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.
+### 2.2 Recover after an interruption
 
-### Arrange the next session and hand off
+Provide the original delivery directory, interrupted action and error. The AI checks saved state, files and unfinished operations while preserving identity and materials. If state saved but the progress page failed, it repairs only the missing view. Repeated activation does not reinitialize.
 
-At a suggested boundary, the agent first confirms that approval, results and state were saved, then reports current results and next work, suggests a new session, and provides one copyable entry using the actual delivery directory:
+Manual progress-page edits are preserved first; conflicts need coordination. Do not approve work by editing that page. If code moves, provide its new location so the AI can check identity before updating the association.
 
-> Use Aimship to continue delivery <actual directory>; first read the current state and relevant formal documents, then continue the recorded work.
+<a id="3-other-starting-points-and-work-arrangements"></a>
+<a id="scenarios"></a>
+<a id="5-other-starting-points-and-work-arrangements"></a>
+<a id="guide-other"></a>
+<a id="2-other-usage-notes"></a>
+<a id="guide-inputs"></a>
 
-You do not need to repeat a session-switch instruction with each approval or separately confirm saving and prompt generation. Say “continue in this session” to proceed. Grouping is a context suggestion, not an approval or blocker. Final handoff has no unnecessary next-stage entry. Ask for a complete prompt when needed; the default is not a long prompt at every stage or a separate prompt/handoff file.
+## 3. Requirements inputs and changes
 
-Aimship itself does not create sessions. After the current session confirms saving and stops writing, open a new session in your AI tool, select Aimship and paste the entry. The new session must uniquely locate the same delivery and inspect actual state, document approval versions, relevant complete formal documents, artifacts and unfinished operations before acting. A trustworthy binding avoids repeated path questions; a missing or ambiguous binding requires a directory or candidate selection, never a guessed latest delivery. Saying “continue next stage” or copying an old prompt grants no approval; a pending draft remains pending across sessions.
+<a id="31-working-from-an-existing-prd-prototype-or-other-materials"></a>
+<a id="working-from-an-existing-prd-prototype-or-other-materials"></a>
+<a id="guide-adoption"></a>
+<a id="23-start-with-an-existing-prd-prototype-or-other-materials"></a>
+<a id="33-turning-the-current-discussion-into-a-delivery"></a>
+<a id="turning-the-current-discussion-into-a-delivery"></a>
+<a id="guide-discussion"></a>
+<a id="25-carry-over-an-existing-discussion"></a>
 
-Keep one writing session per delivery. Code locations and access permissions must remain available; switching sessions cannot bypass reviews or affected-work stops. Progress stays in the same `status.md`, without copying the entire chat.
+### 3.1 Existing materials or discussion
+
+Provide the PRD, prototype or screenshot locations, versions and scope to use. The AI checks them as described in [Confirm requirements](#guide-requirements). Explicitly request direct maintenance of an existing PRD if needed; the AI checks the goal and endpoint before submitting it for review. An existing file is not an approval.
+
+For prior discussion, say “Use Aimship to continue the requirements we just discussed.” The AI organizes visible requests, decisions and open questions. Supply history it cannot see; suggestions are not approvals.
+
+<a id="16-changing-approved-requirements"></a>
+<a id="5-requirements-change-during-delivery"></a>
+<a id="changes"></a>
+<a id="review-verify-and-change"></a>
+<a id="4-requirements-change-during-delivery"></a>
+<a id="changing-approved-requirements"></a>
+<a id="guide-changes"></a>
+<a id="22-change-approved-content"></a>
 
-### Continue after work stops unexpectedly
+### 3.2 Change approved content
 
-If the agent stops because of a lost connection, a tool exit or a canceled operation, describe what it was doing and provide any available errors. Before continuing, the agent checks actual files, saved progress and unfinished operations to establish what completed and avoid repeating writes or other actions with side effects.
+Explain what changes, why, and what stays the same; identify any documents you edited yourself. The AI records important changes in `change-log.md`, resubmits affected documents and holds dependent work until confirmed. Unaffected work, earlier approvals and test history remain.
 
-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.
+Record new requests in requirements and the change log, without overwriting `source/request.md`. Restore accidental edits from a reliable original; if none exists, pause to resolve the gap. Typos and formatting need no full re-review. Small fixes can continue the same delivery; a new goal or major redesign gets a separate delivery linked to the original.
 
-### Continue an existing delivery after upgrading Aimship
+<a id="guide-limits"></a>
+<a id="27-stop-at-a-limited-goal"></a>
 
-After upgrading Aimship, 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.
+### 3.3 Complete only part of the goal
 
+State if you only need requirements or design, or explicitly exclude testing. The AI records the endpoint and omissions, labels the handoff as partial and never marks untested work passed. Asking to “see a preview first” does not change the goal.
+
+Only standalone investigation uses `diagnosis.md`; ordinary debugging adds no investigation stage.
+
+<a id="guide-projects"></a>
+
+## 4. Code and multiple deliveries
+
+<a id="32-changing-a-feature-fixing-a-defect-or-refactoring"></a>
+<a id="34-associating-code-after-requirements-have-started"></a>
+<a id="changing-a-feature-fixing-a-defect-or-refactoring"></a>
+<a id="associating-code-after-requirements-have-started"></a>
+<a id="guide-code"></a>
+<a id="24-change-existing-code-or-associate-it-later"></a>
+
+### 4.1 Associate code, fix defects or refactor
+
+Provide the code directory, for example: “The code is at ‘project directory’; continue the current delivery.” The AI keeps the delivery directory and review records. It may read existing behavior early; edits still follow the agreed scope. Findings affecting approved content return for review. A remote address does not trigger automatic cloning or relocation.
+
+For defects, provide expected behavior, the problem and reproduction steps or logs. For refactoring, state the improvement goal and behaviors to preserve.
+
+<a id="35-progress-several-deliveries-at-once"></a>
+<a id="7-progress-several-deliveries-at-once"></a>
 <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
+<a id="progress-several-deliveries-at-once"></a>
+<a id="guide-parallel"></a>
+<a id="26-work-on-several-requests"></a>
 
-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.
+### 4.2 Work on several requests
 
-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.
+Keep each delivery separate and identify shared code, interfaces, databases or environments. Analysis can run concurrently; sequence edits to the same code, or use separate working directories and plan the merge.
 
-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.
+The AI checks only known, accessible deliveries; it does not lock or schedule other sessions. Describe other ongoing changes and check the merged result afterward.
 
-<a id="completion"></a>
-<a id="decide-when-work-is-done"></a>
-<a id="7-complete-a-delivery"></a>
-## 8. Complete a delivery
+<a id="4-problems-and-references"></a>
+<a id="troubleshoot"></a>
+<a id="8-problems-during-use"></a>
+<a id="9-problems-during-use"></a>
+<a id="6-problems-and-references"></a>
+<a id="guide-troubleshoot"></a>
+<a id="3-access-recovery-and-versions"></a>
+<a id="guide-maintenance"></a>
 
-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.
+## 5. Troubleshooting and maintenance
 
-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.
+<a id="41-common-problems"></a>
+<a id="guide-access"></a>
+<a id="31-workspace-and-access"></a>
 
-Standard complete delivery needs evidence for the main sequence, required document approvals, passing batch/overall reviews, independent verification and final acceptance. `status.md` distinguishes standard completeness from completion of the agreed scope and user acceptance. Tools check records; they cannot independently prove execution or semantic quality. An explicitly limited result can be finished and handed over as partial scope; untested work is labeled untested. Historical outcomes and acceptance remain intact, initially unassessed under the new standard. Inspect evidence and explicitly adopt the new rules before continuing, without inventing historical approvals or tests.
+### 5.1 A directory is inaccessible
 
-Small later corrections can continue the same delivery while preserving its earlier completion record. A new goal or substantial redesign starts a related delivery.
+Use the actual path reported by the AI to add the original delivery directory or grant the needed permissions in your AI tool. If the directory has not been created, use the tool’s supported controls to authorize the necessary parent directory, then continue initialization. Do not copy the delivery or create another one elsewhere.
 
-<a id="troubleshoot"></a>
-<a id="8-problems-during-use"></a>
-## 9. Problems during use
+Reading a file does not prove it can be saved; the AI should report success from actual read/write results. Aimship does not operate permission controls for you. Keep unsaved requests in the current conversation; once access is restored, inspect existing files before continuing. Installation does not automatically create delivery directories or grant access.
 
-| 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 |
+<a id="43-ai-tool-integration-notes"></a>
+<a id="ai-tool-integration-notes"></a>
+<a id="guide-hosts-notes"></a>
+<a id="34-missing-entries-and-host-differences"></a>
+<a id="34-missing-entries-and-ai-tool-differences"></a>
+<a id="guide-tools"></a>
 
-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).
+### 5.2 The Aimship entry is missing
 
-## Related references
+Check installation status through the README, then try a new session or refresh your AI tool’s Skill list and explicitly select Aimship. The available entry depends on the tool’s version and supported controls; a healthy installation does not prove the Skill is loaded.
 
-<a id="artifacts"></a>
-<a id="keep-only-useful-artifacts"></a>
-See [delivery structure and documents](#delivery-structure) for file locations and purposes. For database work or engineering versions, see the [SQL and engineering versions appendix](#document-details).
+For duplicate entries, check their sources and versions while preserving custom content. Codex and Cursor share an installed entry, so do not simply delete duplicates. Real discovery, permissions and cross-tool continuation are not fully verified. See [Cursor documentation](https://cursor.com/docs/skills) and [Codex Skill locations](https://learn.chatgpt.com/docs/build-skills).
+
+<a id="42-continue-an-existing-delivery-after-upgrading-aimship"></a>
+<a id="continue-an-existing-delivery-after-upgrading-aimship"></a>
+<a id="guide-upgrade"></a>
+<a id="33-continue-after-upgrading"></a>
 
+### 5.3 Continue after upgrading
+
+Save current work before [upgrading through the README](../README.md#update). Activate Aimship again afterward and check the actual bound version and delivery state; installation itself does not update delivery records.
+
+Use ordinary Markdown and searchable numbers to record delivery. Check the impact of rule changes and preserve actual approvals and test records without inventing results.
+
+<a id="45-installation-and-maintenance-references"></a>
+<a id="installation-and-maintenance-references"></a>
 <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).
+<a id="guide-references"></a>
+<a id="35-installation-maintenance-and-feedback"></a>
 
-<a id="document-details"></a>
-<a id="sql-changes-and-progress"></a>
-## Appendix: SQL and engineering versions
+### 5.4 Maintenance and feedback
 
-SQL identifies the target, dialect, version/schema basis and execution conditions, and links ordered statements to requirements/design. It is prepared and individually reviewed in contract after technical design approval and before test cases. A Markdown SQL snippet or migration reference does not replace this deliverable. Generating SQL does not authorize executing it or changing a repository's migration mechanism.
+See the [README](../README.md#update) for installation, upgrades, adding AI tools, version and health checks, or [uninstallation](../README.md#uninstall) for removal. Health checks inspect installation files and configuration; they do not repair delivery documents. For an interrupted installation or missing files, follow the corresponding README instructions rather than reinstalling blindly.
 
-Existing engineering HTTP contracts remain authoritative; avoid a second competing copy. Project current and target versions are recorded in PRD/Scope with their engineering source and observation basis; an unspecified version remains unspecified. `plan.md` records actual changes, while review and test results identify the exact commit/build or uncommitted content. Each repository has its own version and object references. These differ from Aimship’s rules version, state schema and save revision. The handoff records final code objects and actual merge/release status; a target version does not establish publication.
+For feedback, provide versions, actions, expected and actual results, and minimal reproduction steps. Redact credentials, personal paths and business data before filing an [Issue](https://github.com/clsx/aimship/issues). See [Contributing](../CONTRIBUTING.md) for development and the [CLI document](cli.md) for tool protocols.