docs: define Co-Build body playbook

SKILL.md

@@ -14,7 +14,7 @@ Code2Lark is the orchestrator and safety boundary. The existing Code2Lark CLI re
 ## Mandatory Routing
 
 1. If the target project already exists and the user wants Lark access added, read `references/retrofit-workflow.md`.
-2. If the user is building a new capability and wants Lark access as part of the work, read `references/cobuild-workflow.md`.
+2. If the user is building a new capability and wants Lark access as part of the work, read `references/cobuild-workflow.md` and then `references/cobuild-playbook.md`.
 3. Before relying on code analysis or external tools, read `references/analyzer-boundary.md`.
 4. Before asking, generating, installing, or enabling actions, read `references/confirmation-policy.md` and `references/safety-and-secrets.md`.
 5. Before card layout or interaction-state decisions, delegate or reference `embedded-skills/lark-card-designer/SKILL.md`; do not duplicate its design rules here.
@@ -26,10 +26,10 @@ The skill should hide command complexity from the user while reusing the existin
 
 | Layer | Responsibility | Examples |
 |---|---|---|
-| Code2Lark Skill | Decide mode, ask questions, control risk, orchestrate commands, summarize evidence. | Retrofit/Co-Build routing, confirmation gates, handoff. |
+| Code2Lark Skill | Decide mode, ask questions, control risk, orchestrate commands, summarize evidence. | Retrofit/Co-Build routing, ownership split, confirmation gates, handoff. |
 | Code2Lark CLI | Execute repeatable operations. | `analyze`, `plan`, `generate`, `install`, `verify`, `doctor`, `evidence`, `handoff`. |
 | External analyzers | Produce optional structural facts. | CodeGraph, dependency-cruiser, ast-grep, ts-morph. |
-| lark-card-designer | Design card structure and interaction states. | Candidate, dry-run, running, success, failure, dangerous-action cards. |
+| lark-card-designer | Design card structure and interaction states. | Candidate, dry-run, confirm, running, success, failure, dangerous-action cards. |
 
 ## Package Layout
 
@@ -67,6 +67,12 @@ what_was_discovered:
 recommended_lark_entrypoints:
 - action, risk, required confirmation
 
+ownership_split:
+- business owner vs Code2Lark responsibilities, especially in Co-Build
+
+cobuild_design_record:
+- activation reason, ownership split, minimal contract, card/action plan, verification and handoff plan
+
 cli_execution_plan:
 - commands to run or commands already run
 

docs/code2lark-localized-core-architecture.md

@@ -32,6 +32,25 @@ The user-facing product is the Code2Lark skill. The CLI remains because it is th
 | Generator/verifier/evidence | Lark integration package, validation, audit, handoff. | Generic code intelligence beyond C2L needs. |
 | Embedded lark-card-designer | Card information architecture and interaction-state design. | Sending cards, credentials, callbacks, or runtime implementation. |
 
+## 2.1 Co-Build Body Capability
+
+Co-Build needs a stronger skill body before it needs more code generation. Retrofit starts from discovered facts; Co-Build starts from a new business intent and must keep ownership clear while the target behavior is still being designed.
+
+The Co-Build body capability is:
+
+```text
+CoBuildDesignRecord
+  activation_reason          # why this is Co-Build, not Retrofit
+  ownership_split            # business owner vs Code2Lark
+  minimal_contract           # target status / dry-run / execute / cancel / audit
+  card_action_plan           # candidate / prepare-or-dry-run / confirm / running / success / failure
+  safety_questions           # unresolved risk, auth, side-effect, or host-surface questions
+  verification_plan          # business evidence + Lark integration evidence
+  handoff_plan               # local secrets, Level 2 evidence, cleanup
+```
+
+The first Co-Build implementation step should be documentation and planning discipline, not a demo-specific generator. A demo should come after the body capability is stable enough to guide another agent without relying on ad hoc conversation memory.
+
 ## 3. OSS Localization Policy
 
 Code2Lark should not ask users to manually operate a pile of external CLIs. OSS capabilities should be localized behind adapters where they materially improve C2L's product loop.
@@ -83,6 +102,8 @@ The desired evolution is not to remove the CLI, but to extract reusable core API
 
 ## 6. First Implementation Slice
 
+This section records the prior localized-core implementation slice that introduced normalized structural graph facts. It is not the Co-Build body capability slice; the Co-Build body is captured above as `CoBuildDesignRecord` and should be validated with a demo after the playbook is stable.
+
 This branch should implement only the smallest useful code step:
 
 1. Add normalized structural graph types.

docs/code2lark-skill-requirements.md

@@ -64,6 +64,10 @@ The analyzer layer should produce facts and uncertainty, not final product decis
 3. Code2Lark owns Lark cards, action contracts, adapter glue, validation, audit, and evidence.
 4. If required business API/state endpoints do not exist, propose a minimal contract and ask before modifying business code.
 5. Keep integration files isolated unless the user explicitly approves touching host project surfaces.
+6. Record an ownership split before proposing generated files or target writes.
+7. Prefer a target contract-first shape for risky work: `status`, `dry-run`, `execute`, optional `cancel/stop`, and audit fields.
+8. Treat `prepare/confirm` as the host-local Lark card pattern unless the business owner explicitly wants target-side prepare/confirm APIs.
+9. Treat Co-Build completion as two-part evidence: business contract behavior plus Lark integration behavior.
 
 ## 6. Confirmation and Card Principles
 
@@ -122,6 +126,7 @@ The MVP skill is acceptable when all of the following are true:
 6. Local verification passes before handoff.
 7. Evidence output is useful without containing real secrets.
 8. Failure modes are explicit: missing credentials, unreachable target, unauthorized operator, stale analysis, unsupported framework, and unsafe action.
+9. Co-Build can produce a reusable synchronized-design record: ownership split, minimal contract, card/action state plan, QA gates, and handoff evidence plan.
 
 ## 10. Product Claim Boundary
 

references/cobuild-playbook.md

@@ -0,0 +1,187 @@
+# Co-Build Playbook
+
+Co-Build mode is the synchronized-design path for a new business capability and its Feishu/Lark entrypoint. The main developer or coding agent owns the business behavior; Code2Lark owns the Lark contract, card/action design, safety boundary, verification plan, and handoff evidence while proposing only the minimal target contract the business owner must approve.
+
+Use this playbook after `cobuild-workflow.md` confirms that the user is explicitly asking for Lark/Feishu access as part of new capability work.
+
+## 1. Activation Checklist
+
+Activate Co-Build only when all are true:
+
+- The user is building or changing a business capability.
+- The user wants that capability reachable from Lark/Feishu, for example via a card, bot action, approval, report, or team-triggered job.
+- There is a clear business owner or main development agent separate from Code2Lark's Lark-integration responsibility.
+
+Do not activate Co-Build for ordinary feature work that has no Lark/Feishu intent. If the project already has finished business behavior and the user only wants Lark access added, use Retrofit instead.
+
+## 2. First Response Shape
+
+When Co-Build activates, respond with this structure before proposing files or commands:
+
+```text
+mode:
+- cobuild
+
+business_capability:
+- what the user wants the business system to do
+- what is still unknown
+
+ownership_split:
+- business owner / main agent owns domain logic, persistence, permissions, and target APIs
+- Code2Lark owns Lark contract, cards, validation, audit, evidence, and generated integration boundary
+
+minimal_contract:
+- proposed status / dry-run / execute / cancel shape
+- missing target APIs or functions, if any
+
+card_confirmation:
+- whether the host-local prepare/confirm card pattern is required
+
+card_design_dependency:
+- which card states require lark-card-designer input
+
+verification_and_handoff:
+- local QA gates
+- real Feishu Level 2 evidence plan, if requested
+```
+
+## 3. Ownership Contract
+
+Co-Build succeeds only if ownership stays explicit.
+
+| Area | Business owner / main agent | Code2Lark |
+|---|---|---|
+| Domain behavior | Owns business rules, data model, persistence, target-side permissions, and side effects. | Does not invent or silently change business rules. |
+| Target API/function surface | Implements or approves any missing status/dry-run/execute/cancel surface. | Proposes the minimal surface needed for Lark integration. |
+| Lark adapter | Provides target operation semantics and safe fields. | Owns card action IDs, adapter boundary, validation, audit fields, and generated integration files. |
+| Risk control | Confirms what is read-only, state-changing, destructive, privileged, or external-send. | Defaults uncertain operations to state-changing or dangerous until confirmed. |
+| Evidence | Confirms business correctness with its own tests. | Proves Lark integration behavior, local verification, and handoff evidence. |
+
+If the business surface is missing, Code2Lark may propose a contract. It must not modify business code, root scripts, deployment files, databases, or production behavior unless the user explicitly approves that scope.
+
+## 4. Minimal Contract Template
+
+Prefer a small, explicit target contract. Not every capability needs all operations, but risky or long-running work should include `dry-run`, `execute`, and `status` where possible.
+
+Terminology matters:
+
+- Target-side contracts use `status`, `dry-run`, `execute`, and `cancel/stop`.
+- `prepare/confirm` is the host-local Lark card action pattern for showing planned effects and then executing after explicit operator confirmation.
+- Do not require the target project to implement `/prepare` or `/confirm` endpoints unless the business owner explicitly wants that API shape.
+
+| Contract part | Purpose | Typical shape | Required when |
+|---|---|---|---|
+| `status` | Read current state or task progress. | `GET /api/<capability>/status` or `getStatus()` | Any long-running, asynchronous, or stateful capability. |
+| `dry-run` | Calculate planned effects without side effects. | `POST /api/<capability>/dry-run` or `execute({ dryRun: true })` | State-changing, destructive, privileged, or external-send operations. |
+| `execute` | Execute after the host-local confirm action approves it. | `POST /api/<capability>/execute` or `execute({ dryRun: false })` | Any operation that changes state or sends externally. |
+| `cancel` / `stop` | Stop or cancel a running operation. | `POST /api/<capability>/cancel` | Long-running work where cancellation is supported and safe. |
+| `audit` | Record who did what, when, and with which result. | Adapter audit event plus target task/correlation ID. | All card actions. |
+
+Minimal contract record:
+
+```json
+{
+  "capability_id": "business.operation",
+  "owner": "business-agent-or-team",
+  "risk": "read_only | write | destructive | privileged | external_send",
+  "inputs": [
+    { "name": "target_id", "required": true, "source": "card_form" }
+  ],
+  "status": { "available": true, "endpoint_or_function": "GET /api/operation/status" },
+  "dry_run": { "available": true, "side_effects": false },
+  "execute": { "available": true, "requires_host_local_confirm": true },
+  "cancel": { "available": false, "reason": "target cannot safely cancel once started" },
+  "audit": ["operator_open_id", "chat_id", "action_id", "target", "trace_id", "result"]
+}
+```
+
+This JSON is a contract sketch for planning and review, not a production schema guarantee.
+
+## 5. Card State Matrix
+
+Before implementing or generating cards, route card design through `embedded-skills/lark-card-designer/SKILL.md`. Code2Lark supplies action semantics and risk; the card designer owns information hierarchy and component choice.
+
+| State | First screen must show | Primary action | Safety rule |
+|---|---|---|---|
+| Candidate | Capability name, owner, source of intent, risk, missing contract questions. | Select or refine capability. | Do not imply the action is ready if contract is incomplete. |
+| Prepare / dry-run | Planned target, inputs, expected effects, warnings, and confidence. | Confirm or edit inputs. | Calls only the target dry-run path or equivalent no-side-effect logic. |
+| Confirm | Final action summary, operator, target, irreversible effects, audit note. | Execute. | Host-local state validates explicit operator confirmation before calling target execute. |
+| Running | Operation ID or trace ID, status, started time, safe refresh. | Refresh or cancel if supported. | Cancel appears only if target contract supports safe cancellation. |
+| Success | Result summary, affected target, timestamp, operator, next safe action. | Refresh status or start another safe run. | Do not expose secrets or raw logs. |
+| Failure | Human-readable error, safe retry path, where to inspect logs. | Retry prepare or refresh status. | Error text must be sanitized. |
+
+## 6. Question Rules
+
+Ask concise questions only when the answer changes the contract or safety boundary. Do not ask broad checklists when a safe default exists.
+
+Ask when:
+
+- Business ownership is unclear.
+- A target API/function is missing and Code2Lark would need to propose one.
+- The operation may change state, delete, deploy, pay, notify, or send externally.
+- The operator allowlist or permission model is unknown.
+- The card's primary action would materially differ based on the user's answer.
+
+Proceed without asking for read-only inspection, draft contracts, reviewable plans, and local analysis that does not write target project files.
+
+## 7. Generation Boundary
+
+Generated files must remain isolated and reviewable.
+
+- Prefer a generated package first.
+- For target-project install mode, default to `integrations/lark`.
+- Use dry-run before `install --apply`.
+- Do not modify root `package.json`, deployment files, Docker files, business routes, migrations, or production config unless explicitly approved.
+- `.env.example` may be generated; real `.env` values must remain local and uncommitted.
+
+## 8. QA and Evidence Gates
+
+Co-Build completion requires both business and Lark-side evidence. A Lark card does not prove business correctness.
+
+| Gate | Owner | Evidence |
+|---|---|---|
+| Business contract test | Business owner / main agent | Target tests or manual proof that status/dry-run/execute/cancel behave as promised. |
+| Adapter validation | Code2Lark | Generated adapter tests, schema checks, and action validation. |
+| Local card simulation | Code2Lark | Simulated card action payloads, success/failure paths, and audit event checks. |
+| Safety check | Code2Lark + business owner | Destructive/privileged/external-send actions use prepare/confirm and allowlist. |
+| Handoff | Code2Lark | Integration README, `.env.example`, verification report, cleanup notes, and Level 2 evidence template. |
+| Real Feishu Level 2 | User/operator, when requested | Sanitized proof of card sent, clicked, callback/action received, target invoked, result updated, and audit recorded. |
+
+Use `references/evidence-handoff.md` for the shared handoff checklist and `references/safety-and-secrets.md` for secret handling.
+
+## 9. Red Lines
+
+- Do not let Code2Lark become the business feature owner.
+- Do not hide missing business APIs behind generated card UI.
+- Do not expose destructive, privileged, payment, deployment, deletion, or external-send operations as one-click actions.
+- Do not treat card visibility as authorization.
+- Do not commit or print real app secrets, open IDs, chat IDs, message IDs, raw callbacks, access tokens, debug tokens, or `.env` values.
+- Do not claim Co-Build is complete until both the business contract and the Lark integration path have evidence.
+
+## 10. Completion Report
+
+Report Co-Build work in this shape:
+
+```text
+mode:
+- cobuild
+
+business_contract:
+- implemented, proposed, or blocked
+
+lark_entrypoints:
+- cards/actions, risk, confirmation model
+
+ownership:
+- what business owner owns
+- what Code2Lark owns
+
+verification:
+- business tests or missing business evidence
+- adapter/card simulation/verify results
+
+handoff:
+- generated files, local-only secrets/evidence, remaining real Feishu steps
+```
+
+This report is the conversational form of a `CoBuildDesignRecord`: activation reason, ownership split, minimal target contract, card/action plan, safety questions, verification plan, and handoff plan.

references/cobuild-workflow.md

@@ -6,6 +6,8 @@ Co-Build mode is used when a new business capability and its Feishu/Lark entrypo
 
 Let the main developer or coding agent own business behavior while Code2Lark owns Lark-facing contracts, cards, validation, audit, and evidence.
 
+After confirming Co-Build mode, use `cobuild-playbook.md` as the operating manual. This file decides whether Co-Build applies; the playbook defines how to run synchronized design.
+
 ## Activation Rule
 
 Activate only when the user expresses Feishu/Lark intent, for example:
@@ -22,24 +24,50 @@ Do not activate for ordinary feature work without Lark/Feishu intent.
 1. **Clarify ownership**
    - Main business agent/developer owns domain logic, persistence, and target API behavior.
    - Code2Lark owns adapter boundary, card actions, validation, audit, and handoff.
+   - Record this split before proposing target writes or generated files.
 
 2. **Define minimal contract**
    - If target APIs already exist, reuse them.
    - If missing, propose minimal endpoints or function contracts and ask before changing host code.
    - Prefer explicit `status`, `dry-run`, `execute`, and `cancel/stop` contracts when long-running or risky.
+   - Use `cobuild-playbook.md` for the contract template and question rules.
 
 3. **Design Lark interaction**
    - Use `../embedded-skills/lark-card-designer/SKILL.md` for information architecture and card states.
    - Code2Lark supplies action type, risk level, required inputs, audit metadata, and side-effect boundary.
+   - Use the playbook card state matrix: candidate, prepare/dry-run, confirm, running, success, failure.
 
 4. **Generate isolated integration**
    - Keep files under an integration boundary such as `integrations/lark` unless the user approves host-surface changes.
 
 5. **Verify continuously**
    - Validate contract tests, local action simulation, target reachability, and evidence outputs.
+   - Separate business correctness evidence from Lark integration evidence.
+
+## Required Outputs
+
+- `CoBuildDesignRecord`: activation reason, ownership split, target contract, card/action plan, safety questions, verification plan, and handoff plan.
+- Ownership split: who owns business behavior and who owns Lark integration.
+- Minimal target contract: status/dry-run/execute/cancel/audit availability and gaps.
+- Card confirmation model: whether host-local prepare/confirm is required before target execute.
+- Card/action plan: states, risk, confirmation model, and audit fields.
+- Verification plan: business tests, adapter simulation, safety checks, and handoff evidence.
+
+## Terminology
+
+- **Target contract** means business APIs or functions such as `status`, `dry-run`, `execute`, and `cancel/stop`.
+- **Prepare/confirm** means the host-local Lark card action pattern: prepare or dry-run shows planned effects; confirm calls the approved execute path.
+- Do not require target-side `/prepare` or `/confirm` endpoints unless the business owner explicitly approves that API shape.
 
 ## Non-Goals
 
 - Do not invent business requirements.
 - Do not silently modify root package scripts, deployment files, or business routes.
 - Do not treat the Lark card as proof that the underlying business behavior is correct.
+
+## Acceptance Signals
+
+- A different agent or developer can implement the business contract without guessing Code2Lark intent.
+- Code2Lark can design the Lark entrypoint without owning business logic.
+- Risky actions have dry-run or prepare/confirm separation before real execution.
+- Handoff states both business evidence and Lark integration evidence.