feat(skills): add develop workflow
This commit is contained in:
@@ -0,0 +1,45 @@
|
||||
# Evidence and recovery
|
||||
|
||||
## Checkpoint records
|
||||
|
||||
Keep one concise Markdown record in the repository's established plan location; otherwise use `docs/plans/<feature-branch-slug>.md`. Require a unique path before creation. Store status/current phase, request/scope, Git identity, acceptance criteria, exact approved plan and gate decisions, assignment ownership, verification outcomes, review identities/findings/fingerprint, integration, blockers, and the next safe action.
|
||||
|
||||
Keep transcripts, leases, heartbeats, notification receipts, full command output, and model-authored execution graphs out of the record. Link durable artifacts or commits instead. Update only at meaningful boundaries; task tools hold high-frequency progress.
|
||||
|
||||
Prepare the complete candidate outside the record's same-directory temporary namespace and run:
|
||||
|
||||
```bash
|
||||
node skills/develop/develop-workflow/scripts/checkpoint-record.mjs \
|
||||
<record.md> --input <candidate.md> --expected-sha256 <current-digest>
|
||||
```
|
||||
|
||||
Omit `--expected-sha256` only for first creation; require an absent target. Commit the initial record and every approved gate before dependent product mutation. A stale digest, lock, temporary artifact with no valid record, validation failure, or filesystem error blocks progress. Preserve artifacts for inspection; never hand-delete recovery evidence to make a command pass.
|
||||
|
||||
## Assignment evidence
|
||||
|
||||
Before every mutating assignment, record:
|
||||
|
||||
- display name, profile, stable child/session IDs when exposed;
|
||||
- deadline and exclusive owned paths;
|
||||
- branch, HEAD, clean/dirty status, changed paths, and patch artifact.
|
||||
|
||||
After delivery, capture the same Git evidence and inspect the patch. Treat the entire ambiguous profile/run as a mutator when stable identity is unavailable. Reject unexpected commits and paths outside ownership.
|
||||
|
||||
On an ownership or Git invariant failure, freeze mutation and present evidence-backed choices: inspect, accept and replan, restore with a non-destructive patch, or abort. Obtain a user decision before proceeding.
|
||||
|
||||
On deadline expiry or missing delivery, request stop through the available control surface and prove the process/session terminal before reassignment. A completed UI indicator is not output or liveness proof. Keep the workflow blocked for human termination/takeover when liveness remains unknown.
|
||||
|
||||
## Fresh-session recovery
|
||||
|
||||
Reconstruct observed reality before trusting prose:
|
||||
|
||||
1. Read repository instructions; inspect worktrees, branches, refs, status, commits, and diff.
|
||||
2. Discover candidate records from observed branches/worktrees and repository conventions.
|
||||
3. Treat a workflow branch/worktree without a record as an orphan. Preserve it; inspect branch, base, reflog, status, commits, and diff; ask whether to adopt it with a record, quarantine it, or remove it after separate cleanup approval.
|
||||
4. Compare the record's base, branch, and checkpoint with Git evidence.
|
||||
5. Preserve atomic-update temporary files. Use the last committed valid record until recovery is approved.
|
||||
6. Rebuild task state from completed evidence and the recorded next action.
|
||||
7. Freeze interrupted mutation until its diff is inspected and prior child liveness is terminal.
|
||||
8. Resume from the last proven checkpoint.
|
||||
|
||||
Ask when evidence conflicts, scope may have changed, child liveness is unknown, or recovery needs risk. Treat the record as a recovery map, not a transaction log.
|
||||
@@ -0,0 +1,40 @@
|
||||
# Git and local integration
|
||||
|
||||
## Isolation
|
||||
|
||||
Record the source branch and exact base before creating `./.worktrees/<feature>` on `feature/<feature>`. Prove every shell location with explicit `cd` or `git -C`; verify `git rev-parse --show-toplevel` before mutation. Block on collisions, unmerged paths, unexpected ownership, or an unignored worktree root. Never rename, reset, clean, stash, copy source changes, or remove an orphan silently.
|
||||
|
||||
A dirty source checkout requires bounded status/path evidence and explicit approval because its changes are omitted. Preserve that evidence in the record.
|
||||
|
||||
## Synchronize and pin review
|
||||
|
||||
After focused commits and verification:
|
||||
|
||||
1. Fetch the latest source branch when a remote exists.
|
||||
2. Rebase the feature branch onto the latest source commit.
|
||||
3. Rerun affected checks and full required verification whenever rebase changes the effective tree or resolves conflicts.
|
||||
4. Record the review base, product HEAD, clean status, tree hash, and commit list.
|
||||
5. Generate exact review bytes:
|
||||
|
||||
```bash
|
||||
git diff --binary --full-index --find-renames <base>...<product-head> --
|
||||
```
|
||||
|
||||
6. Hash those bytes with SHA-256 and record the command and digest. Regenerate from the durable commits rather than committing a duplicate patch.
|
||||
|
||||
Ask before conflict resolution changes approved behavior, history rewrite of shared work, force operations, or non-fast-forward integration.
|
||||
|
||||
## Fast-forward integration
|
||||
|
||||
After both review axes approve the exact fingerprint:
|
||||
|
||||
1. Confirm the source branch still equals the final rebase base. Return to synchronize, verify, and review if it advanced.
|
||||
2. Confirm the source checkout exists, is clean, and is safe to update. Stop when dirty or missing.
|
||||
3. Fast-forward the source branch to the reviewed feature branch; create no merge commit.
|
||||
4. In the source checkout, update only the workflow record with bound review and integration evidence.
|
||||
5. Prove the closure diff touches only that record, run applicable documentation checks, and create one metadata-only closure commit.
|
||||
6. Run a cheap final sanity check.
|
||||
7. Prove the product and closure commits reachable from the source branch.
|
||||
8. Remove the completed worktree, then delete its feature branch.
|
||||
|
||||
Treat cleanup in step 8 as pre-authorized only after every preceding clean-state and reachability proof. Ask before any other destructive cleanup. Pushing, publishing, deployment, and production access remain separate user actions.
|
||||
@@ -0,0 +1,33 @@
|
||||
# Independent review and remediation
|
||||
|
||||
## Identity and capability
|
||||
|
||||
Exclude every identity that authored or mutated the reviewed diff. Record reviewer display name, profile, child ID, and session ID when available. When stable identity is unavailable, exclude the entire ambiguous profile/run. Keep reviewers read-only and separate for:
|
||||
|
||||
- **Standards:** repository instructions and documented conventions.
|
||||
- **Specification:** the approved workflow record and linked source plan/spec.
|
||||
|
||||
Use Git-capable reviewer profiles with repository read access and no declared `write` or `edit` tools. Shell access can still mutate; capture status, tree, HEAD, and changed paths before and after review. Any mutation invalidates the verdict and marks that identity as a mutator.
|
||||
|
||||
## Review brief
|
||||
|
||||
Generate the brief in the parent. Include:
|
||||
|
||||
- pinned base and product HEAD;
|
||||
- clean status and product tree hash;
|
||||
- commit list;
|
||||
- exact `git diff --binary --full-index --find-renames <base>...<product-head> --` command;
|
||||
- SHA-256 of those exact bytes;
|
||||
- approved record/specification sources;
|
||||
- repository standards sources;
|
||||
- all excluded mutator identities.
|
||||
|
||||
Launch standards and specification reviewers through separate direct subagent calls. Avoid wrapped parallel launch until its delivery defect is proven fixed. Require each reviewer to regenerate the pinned diff, confirm its digest before review, remain read-only, and bind every finding to file/hunk evidence and severity. Treat a missing result or digest mismatch as no verdict.
|
||||
|
||||
Approval binds to base, product HEAD, clean status, tree hash, and diff digest. Permit a later closure commit outside that fingerprint only after proving it changes the workflow record alone.
|
||||
|
||||
## Findings and remediation
|
||||
|
||||
Validate findings against repository evidence. Send accepted fixes to an original implementer or another non-reviewer, never the reviewer. Preserve exclusive path ownership and assignment evidence. Rerun affected checks and the full required suite, create focused commits, and generate a new fingerprint.
|
||||
|
||||
Launch fresh independent reviewers for the changed diff. Escalate after two unsuccessful remediation cycles or whenever a finding requires material scope, acceptance, ownership, verification, or architecture changes; return to plan approval before further production mutation.
|
||||
Reference in New Issue
Block a user