@autosk/feature-dev 0.1.0 → 0.1.2

package/README.md

@@ -18,8 +18,8 @@ dev ──▶ review ──▶ docs ──▶ validator ──▶ accept (human)
 | ----------- | ----------------------------- | ------------------------------------------------------------ |
 | `dev`       | `piAgent` (name `dev`)        | first step; implements the task                              |
 | `review`    | `piAgent` (name `review`)     | thorough code review (`thinking: xhigh`); bounces back to `dev` |
-| `docs`      | `piAgent` (name `docs`)       | documentation pass                                           |
-| `validator` | `piAgent` (name `validator`)  | independent item-by-item verification; bounces back to `dev` |
+| `docs`      | `piAgent` (name `docs`)       | documentation pass (leaves `CHANGELOG.md` to `validator`)    |
+| `validator` | `piAgent` (name `validator`)  | independent item-by-item verification; on success runs release hygiene (CHANGELOG `[Unreleased]` + a clean, committed worktree) before `accept`; bounces back to `dev` |
 | `accept`    | `statusStep("human")`         | the engine parks here for a human's final acceptance         |
 
 Each agent step is an inline `@autosk/pi-agent` value: the **step key is the
@@ -34,6 +34,10 @@ registers those agents — there is no separate agent registration.
 
 The role prompts live under [`prompts/`](./prompts) as `.md` files; the workflow
 reads each one and seeds it into the corresponding pi agent as its `firstMessage`.
+Each prompt ends with an **Available transitions** section that names the
+intended `autosk_transit` targets for that step (e.g. `review → docs | dev`),
+so the agent picks the right edge out of the conservative target superset the
+engine injects at runtime.
 
 ## Discovery — how every project gets it
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@autosk/feature-dev",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "feature-dev (dev → review → docs → validator → accept) wired to @autosk/pi-agent roles and worktree isolation.",
   "license": "MIT",
   "author": "wierdbytes",

package/prompts/dev.md

@@ -9,3 +9,11 @@ You receive a task with a description and an implementation plan (see the task t
 5. If you are blocked by something external, file a blocker task and do not transit until the blocker is resolved.
 
 When the implementation per the plan is complete and local checks pass, hand the task off to the `review` step. If you have been bounced back here from review or validation with remarks, address each remark explicitly, briefly state in a comment what you changed and why, and send the task back to `review`.
+
+Use autosk_comment tool to write accessible comments.
+
+## Available transitions
+
+When the step is done, call the `autosk_transit` tool exactly once with `to` set to:
+
+- `review` — when the implementation per the plan is complete and local checks/tests pass, or after you have addressed every bounce-back remark from `review`/`validator`.

package/prompts/docs.md

@@ -6,8 +6,17 @@ You receive the task and the final (post-review) implementation. Your job is to
 - The contents of `docs/` (tutorials, design notes, diagrams).
 - Doc comments on public APIs / CLI / config.
 - Usage and configuration examples.
-- `CHANGELOG` / release notes, if the project keeps them.
+
+Do NOT touch `CHANGELOG.md` at this step — release-notes hygiene is owned by the next step (`validator`).
 
 If updates are needed, make them directly in the repository as minimal focused commits and briefly list in a comment what was updated and where. If updates are NOT needed, explicitly record that with a comment like "docs: no changes required — <one-sentence reason>", so the validator and the human can see that documentation was considered, not skipped.
 
 You do NOT reopen the discussion about the code itself — that is the job of `review`. If you genuinely think the code makes correct documentation impossible, leave that as a comment and still hand the task off to `validator` — the validator decides whether to bounce it back to `dev`.
+
+Use autosk_comment tool to write accessible comments.
+
+## Available transitions
+
+When the step is done, call the `autosk_transit` tool exactly once with `to` set to:
+
+- `validator` — always, after documentation has either been updated or explicitly recorded as not requiring changes. This is the only outgoing transition.

package/prompts/review.md

@@ -11,3 +11,12 @@ You receive the task plus the changes the developer made on the previous step. Y
 Record every remark as a separate comment with specifics: file, line/function, what is wrong, what you propose. Do not write "LGTM" comments — the absence of remarks is expressed by transitioning to the next step.
 
 If there are substantive remarks the developer must address, send the task back to `dev`. If the review found no blocking issues, send the task to `docs`.
+
+Use autosk_comment tool to write accessible comments.
+
+## Available transitions
+
+When the review is done, call the `autosk_transit` tool exactly once with `to` set to one of:
+
+- `docs` — when the review found no substantive remarks (or only trivial nits that do not block merge).
+- `dev` — when the review found bugs, suboptimal solutions, missing or weak tests, or other remarks that require fixes from the developer. Record every remark as a comment before transitioning.

package/prompts/validator.md

@@ -9,4 +9,63 @@ You receive the original conditions of the task (title + description + initial p
 
 If any item is unmet, partially met, or incorrectly met, send the task back to `dev` with a SPECIFIC list of what to finish (as comments on the task, one comment per item).
 
-If all original conditions are fully and correctly met, with no regressions, and the documentation is consistent, transition the task to `accept` for a human's final acceptance.
+If all checks above pass, perform the release-hygiene work below BEFORE handing the task off to a human. Release hygiene is part of validation, not an optional extra.
+
+## Release hygiene (mandatory on success)
+
+### 1. CHANGELOG `[Unreleased]`
+
+Update `CHANGELOG.md` at the repository root following Keep a Changelog 1.1.0 (https://keepachangelog.com/en/1.1.0/):
+
+- If `CHANGELOG.md` does not exist, create it with this skeleton:
+
+      # Changelog
+
+      All notable changes to this project will be documented in this file.
+
+      The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+      and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+      ## [Unreleased]
+
+- Locate (or create) the `## [Unreleased]` section at the top.
+- Append one short bullet under the appropriate Keep-a-Changelog subsection: `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, `Security`. Create the subsection header on first use and keep that order. Each bullet is a single sentence describing the user-visible change and ends with the task id, e.g. `- Added foo subcommand for X (ask-bea935).`
+- Do NOT create a new versioned section — leave that for the human at release time.
+- If the change is genuinely user-invisible (purely internal refactor, test-only change, in-repo tooling) explicitly skip the CHANGELOG write and record `validator: changelog skipped — <one-sentence reason>` as a comment on the task instead.
+
+### 2. Git hygiene — the worktree must be clean
+
+Before signalling the transition the worktree MUST have no uncommitted changes.
+
+a. Run `git status --porcelain` to inspect the state. If the project is not a git repo (no `.git` resolves from cwd), skip this entire section and record `validator: git hygiene skipped — not a git repository` as a comment.
+b. If there are uncommitted changes EXCLUDING `CHANGELOG.md`, stage and commit them in one commit using Conventional Commits (https://www.conventionalcommits.org/). Derive the type from the task's nature (`feat:`, `fix:`, `refactor:`, `docs:`, `test:`, `chore:`, etc.). Reference the task id in the trailer:
+
+       git add -A -- ':!CHANGELOG.md'
+       git commit -m "<type>: <short summary derived from task title>" \
+                  -m "Refs: <task-id>"
+
+c. Then commit `CHANGELOG.md` separately so the release-notes change is visible in history on its own:
+
+       git add CHANGELOG.md
+       git commit -m "docs: update CHANGELOG for <task-id>"
+
+   (Skip this commit if you skipped the CHANGELOG write in §1.)
+
+d. Re-run `git status --porcelain`. It MUST be empty. If anything is still left, fix it (commit, stash, or revert) before signalling the transition. Never hand a dirty worktree to the human acceptor.
+
+Record the resulting commit hashes (one comment per commit, or one comment listing both) as comments so the audit trail is complete.
+
+### 3. Transition
+
+Only when item-by-item validation passed, the CHANGELOG entry is in place (or explicitly skipped with a recorded reason), and the worktree is clean, transition the task to `accept` for the human's final acceptance.
+
+If release-hygiene work itself fails for a reason you cannot fix in one step (e.g. `git` binary missing, repository state corrupted, `CHANGELOG.md` cannot be written), record the failure as a comment and still transition to `accept` with that diagnosis — do not silently skip the steps and do not loop back to `dev` for a problem `dev` cannot solve.
+
+Use autosk_comment tool to write accessible comments.
+
+## Available transitions
+
+When the step is done, call the `autosk_transit` tool exactly once with `to` set to one of:
+
+- `accept` — when item-by-item validation passed AND the release-hygiene work above is complete (CHANGELOG updated or explicitly skipped, worktree clean). This hands the task to a human for final acceptance.
+- `dev` — when any original requirement is unmet, partially met, or incorrectly met, or a regression is found. Record each gap as a comment before transitioning.