| name | appsdk-project-governance |
| description | Apply AppSDK engineering quality gates, project contracts and lifecycle evidence. Use optional Guidance for planning; keep automatic multi-worker Collab separate from quality admission. |
AppSDK Project Governance
Purpose and mandatory boundary
AppSDK verifies engineering quality. Collab supports automatic multi-worker
registration, communication and task/file ownership. Memory and Guidance help
when useful. Missing auxiliary state does not fail independent development.
Default flow: understand goal/scope → implement → relevant verification →
review → authorized delivery. Require applicable quality, safety and evidence
integrity gates; do not turn every available command into a mandatory phase.
Run project commands from project cwd. An explicit optional project path is for
operators intentionally working elsewhere; no project-root environment variable.
Working loop
- Read project AGENTS and affected code/contracts. Resolve owner, scope,
acceptance and relevant gates. Read historical notes only when they help.
- Use a clean owner worktree from latest origin/main. Preserve others' work.
For multi-worker work, automatically register the peer, communications and
task/file scope through official Collab; enforce overlap/resource ownership.
- Implement the smallest adequate change. Use existing design for local work;
clarify only material unknowns. Do not require a new plan or approval when
scope is already authorized and clear.
- Run applicable tests, necessary build and actual entrypoint checks. Install
and restart only when required by the delivery object. Fix failures at their
owner, never forge evidence or hide errors.
- Review exact validated changes under the shared review standard. Block
concrete correctness, safety, contract or material structural regressions;
optional simplifications are advisory.
- Reuse still-valid evidence when relevant source, inputs, dependencies,
configuration, artifact and environment remain unchanged. Rerun affected
checks after changes; verify an altered integration candidate.
- Deliver within authorization. Report test, review, merge, install, publish
and resource cleanup as separate achieved states.
Optional Guidance
Use appsdk guide status/init/plan/update/next/close when the user/project
selects persistent planning or a long task benefits from recovery. Default
advisory and warning do not require a task plan or setup before development.
Missing PlanRecord does not fail ordinary verify or compile.
When using Guidance, follow its declared transitions and bind observations to
the current context. A failed optional workflow is not a failed quality gate.
Do not fabricate a successful step to close a plan.
For a requested setup/upgrade, guide init --mode bootstrap is read-only.
Compare current project-owned sources with the advisory standard template;
apply only authorized rule changes. appsdk init refreshes SDK resources but
never overwrites project AGENTS, Skills, records, Active or Protected. Merely
auditing rules does not require running initialization or changing setup.
Automatic Collab
appsdk init attempts official collab init once in a live tmux peer, preserving
the inherited environment. Successful initialization registers identity and the
finite direct-message subscription. Do not duplicate that initialization.
Once task/worktree scope is known, use the Collab task lifecycle to register
feature/resource and file ownership before concurrent edits. Do not invent
task scope inside AppSDK initialization.
No tmux peer means pending. An unavailable/failed Collab reports its error;
independent work continues, while operations requiring shared ownership wait.
Keep automatic communication and file/task collaboration enabled; a serial
merge queue is required only when the project selects that integration mode.
Its ownership and tested-integration protections remain mandatory.
Evidence and state ownership
- Project AGENTS owns project facts; Skills own procedure; declared machine
contracts own enforceable gates. Existing lifecycle records remain the sole
evidence truth. Plans, notes and Collab statuses do not duplicate PASS.
- Runtime review admission retains whitebox, public-entrypoint blackbox and
exact candidate/artifact/environment identity. Module
deployment_operations
declares required install/restart receipts; omission retains both for
compatibility, [] means neither operation applies. Bind this choice before
validation; changes invalidate artifact identity. Every supplied receipt is
checked. A missing required capability remains a blocker.
- Review confidence scores are optional annotation, never proof of quality.
- Freeze/Active/Protected apply when immutable artifact publication is in
scope. Do not require freezing for a documentation edit or ordinary review.
- Engineering delivery may complete with a retained worktree. Keep ownership
and cleanup obligations explicit; only claim resource closure after actual
safe cleanup. No forced deletion to make a task appear complete.
- Memory is optional. No automatic durable memory/rule promotion. Long tasks
and handoffs may record concise decisions and references to existing evidence.
Memory migration and re-entry are explicit independent operations: use
project-memory migrate for a source-preserving, resumable schema move and
project-memory reentry [project] --run <run-id> to resume the same run after
interruption. A missing or rebuilding memory index is not a governance
failure, and memory state must not be reconstructed from Guide, debug,
develop, or log payloads.
References: load only the relevant domain
Failure reports name the failed applicable gate, preserved state, owner and next
action. Never infer deployed success, merge, freeze or cleanup from an earlier
test or an auxiliary workflow close.
