diff --git a/SKILL.md b/SKILL.md index e497e84..2a8a077 100644 --- a/SKILL.md +++ b/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 diff --git a/docs/code2lark-localized-core-architecture.md b/docs/code2lark-localized-core-architecture.md index dcd18e1..f8e5055 100644 --- a/docs/code2lark-localized-core-architecture.md +++ b/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. diff --git a/docs/code2lark-skill-requirements.md b/docs/code2lark-skill-requirements.md index 674dcee..8b183d7 100644 --- a/docs/code2lark-skill-requirements.md +++ b/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 diff --git a/references/cobuild-playbook.md b/references/cobuild-playbook.md new file mode 100644 index 0000000..3b94972 --- /dev/null +++ b/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//status` or `getStatus()` | Any long-running, asynchronous, or stateful capability. | +| `dry-run` | Calculate planned effects without side effects. | `POST /api//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//execute` or `execute({ dryRun: false })` | Any operation that changes state or sends externally. | +| `cancel` / `stop` | Stop or cancel a running operation. | `POST /api//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. diff --git a/references/cobuild-workflow.md b/references/cobuild-workflow.md index 14c744b..9bb4eb8 100644 --- a/references/cobuild-workflow.md +++ b/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.