From 92fd87bbd505346bf0f3cc37784d2f314f05a227 Mon Sep 17 00:00:00 2001 From: Deepak Date: Tue, 5 May 2026 00:57:10 +0530 Subject: [PATCH 1/3] Add Phasekeeper skill --- skills/.curated/phasekeeper/LICENSE.txt | 202 ++++++++++++++++++ skills/.curated/phasekeeper/SKILL.md | 138 ++++++++++++ .../.curated/phasekeeper/agents/openai.yaml | 4 + .../phasekeeper/assets/templates/AGENTS.md | 65 ++++++ .../phasekeeper/assets/templates/PROGRESS.md | 37 ++++ .../phasekeeper/assets/templates/WORKFLOW.md | 181 ++++++++++++++++ .../assets/templates/docs-boards-README.md | 27 +++ .../assets/templates/phase-board.md | 126 +++++++++++ .../assets/templates/phase-spec.md | 51 +++++ .../phasekeeper/scripts/init_phasekeeper.py | 82 +++++++ 10 files changed, 913 insertions(+) create mode 100644 skills/.curated/phasekeeper/LICENSE.txt create mode 100644 skills/.curated/phasekeeper/SKILL.md create mode 100644 skills/.curated/phasekeeper/agents/openai.yaml create mode 100644 skills/.curated/phasekeeper/assets/templates/AGENTS.md create mode 100644 skills/.curated/phasekeeper/assets/templates/PROGRESS.md create mode 100644 skills/.curated/phasekeeper/assets/templates/WORKFLOW.md create mode 100644 skills/.curated/phasekeeper/assets/templates/docs-boards-README.md create mode 100644 skills/.curated/phasekeeper/assets/templates/phase-board.md create mode 100644 skills/.curated/phasekeeper/assets/templates/phase-spec.md create mode 100755 skills/.curated/phasekeeper/scripts/init_phasekeeper.py diff --git a/skills/.curated/phasekeeper/LICENSE.txt b/skills/.curated/phasekeeper/LICENSE.txt new file mode 100644 index 00000000..7a4a3ea2 --- /dev/null +++ b/skills/.curated/phasekeeper/LICENSE.txt @@ -0,0 +1,202 @@ + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. \ No newline at end of file diff --git a/skills/.curated/phasekeeper/SKILL.md b/skills/.curated/phasekeeper/SKILL.md new file mode 100644 index 00000000..f3847470 --- /dev/null +++ b/skills/.curated/phasekeeper/SKILL.md @@ -0,0 +1,138 @@ +--- +name: phasekeeper +description: Use when setting up or operating a Phasekeeper workflow for Codex projects with active phase boards, approved specs, session start gates, issue tracking, verification logs, progress archives, and clean handoffs. +metadata: + short-description: Board-first workflow for long-running Codex projects +--- + +# Phasekeeper + +Phasekeeper is a board-first workflow for long-running software work. It keeps Codex anchored to explicit phase state instead of relying on chat memory. + +Use this skill when the user asks to install, set up, start, continue, close, or repair a Phasekeeper-managed project. + +## Operating Rules + +1. If the target repo has `AGENTS.md`, read and obey it first. +2. Treat `docs/boards/README.md` as the active phase pointer. +3. Treat the active board as the current state of work. +4. Do not start implementation until the session start gate is complete and the operator confirms. +5. Do not infer phase scope from chat when a board or spec is missing. Create or request the missing workflow artifact. +6. Keep workflow updates auditable: references, tests, issues, work log, progress, and commits should agree. + +## Setup Mode + +Use setup mode when the user asks to set up, install, initialize, bootstrap, or add Phasekeeper to a repo. + +Steps: + +1. Inspect the target repo for existing `AGENTS.md`, `WORKFLOW.md`, `PROGRESS.md`, `docs/boards/README.md`, and `docs/specs/`. +2. If this skill's script is available, run `scripts/init_phasekeeper.py `. +3. If existing files are present, do not overwrite them unless the user explicitly asks for overwrite behavior. +4. Report which files were created, skipped, or overwritten. +5. Tell the user that future sessions should start with the Phasekeeper session start protocol. + +If the script is unavailable, create the same files from `assets/templates/`. + +## Session Start + +Use session start when the user asks to start, resume, continue, pick up, or check current Phasekeeper state. + +Read in this order: + +1. `AGENTS.md`, if present. +2. `docs/boards/README.md`. +3. The active board listed by `docs/boards/README.md`, if it exists. +4. The active spec listed by the board, if it exists. +5. `WORKFLOW.md`. +6. Any OPEN issues on the active board. + +Then report exactly: + +```text +Phase NN, Step K of N. Open issues: N. Next up: . Ready? +``` + +Wait for operator confirmation before implementation. + +If an active board does not exist, switch to board creation mode. If the phase spec does not exist or is not approved, switch to spec mode. + +## Spec Mode + +Use spec mode when a phase needs a written plan before implementation. + +Create or update: + +```text +docs/specs/phase_NN_.md +``` + +The spec must define: + +- Goal and non-goals. +- Scope boundaries. +- Behavior, API, schema, or contract changes. +- Configuration changes. +- Tests and verification gates. +- Implementation order. +- Open questions. + +Do not mark a spec approved unless the operator explicitly approves it. + +## Board Creation Mode + +Use board creation mode when a spec is approved but no board exists. + +Create: + +```text +docs/boards/phase_NN_.md +``` + +Base it on `docs/boards/phase-board.template.md`. Populate the implementation steps from the approved spec. Update `docs/boards/README.md` so exactly one phase is active. + +## Phase Work Mode + +Use phase work mode only after the operator confirms the session start prompt. + +For each active step: + +1. Check worktree state. +2. Read every file the step will touch and the relevant tests. +3. Write or update the narrowest relevant test when behavior changes. +4. Implement the minimal scoped change. +5. Run relevant verification. +6. Update board References, Tests, Issues, and Work Log. +7. Update `PROGRESS.md` after the session or accepted phase. +8. Commit completed board steps unless the operator says not to. + +Do not mix unrelated cleanup into a phase step. + +## Session Close + +Use session close when the user asks to stop, wrap up, close, hand off, finish the session, or summarize next steps. + +Before final response: + +1. Update the active board Current Status. +2. Add a Work Log entry with what changed, verification, issues, and next step. +3. Update References for every created or modified file. +4. Update Tests with exact commands and results. +5. Update `PROGRESS.md`. +6. Run `git status --short`. +7. Run `git log --oneline -10`. +8. Commit completed board steps unless the operator says not to. +9. Tell the operator exactly where the next session picks up. + +If a board marks a step DONE but no matching commit exists, say so explicitly. + +## Hard Stops + +Stop and ask the operator when: + +- The active board or spec contradicts the repo state. +- A test suggests the spec is wrong. +- A high-severity issue appears. +- A change would weaken a stated invariant or project rule. +- A design decision has multiple valid options. +- You are tempted to patch around a symptom instead of fixing the root cause. diff --git a/skills/.curated/phasekeeper/agents/openai.yaml b/skills/.curated/phasekeeper/agents/openai.yaml new file mode 100644 index 00000000..524e93d7 --- /dev/null +++ b/skills/.curated/phasekeeper/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Phasekeeper" + short_description: "Board-first workflow for long-running Codex projects" + default_prompt: "Use Phasekeeper to set up this repo, start a session, or close a session with board-first handoff discipline." diff --git a/skills/.curated/phasekeeper/assets/templates/AGENTS.md b/skills/.curated/phasekeeper/assets/templates/AGENTS.md new file mode 100644 index 00000000..c191b3e3 --- /dev/null +++ b/skills/.curated/phasekeeper/assets/templates/AGENTS.md @@ -0,0 +1,65 @@ +# Phasekeeper Agent Rules + +This repository uses Phasekeeper: a board-first workflow for long-running agent-assisted software projects. + +Optimize for correctness, traceability, and clean handoff. Speed and convenience are secondary when they conflict with those goals. + +Where this file conflicts with `WORKFLOW.md`, this file wins. + +--- + +## Session Start + +Before implementation work: + +1. Read `docs/boards/README.md`. +2. Read the active board listed there, if it exists. +3. Read the active spec listed by the board, if it exists. +4. Read `WORKFLOW.md`. +5. Check the active board for OPEN issues. +6. Tell the operator: `Phase NN, Step K of N. Open issues: N. Next up: . Ready?` +7. Wait for operator confirmation before implementation. + +If the active board does not exist, read `WORKFLOW.md` and follow the board/spec creation process. Do not infer phase scope from chat alone. +If the active spec is missing or still marked `DRAFT`, stop in spec mode and get explicit operator approval before creating a board or implementing. + +--- + +## During Work + +- Follow the active board one step at a time. +- Do not merge unrelated refactors or cleanup into a phase step. +- If the work changes behavior, write or update tests before implementation when feasible. +- Keep changes scoped to the active phase or explicit operator request. +- Preserve existing local changes that are unrelated to your task. +- Log issues on the active board when found. +- Stop and ask when a decision has multiple valid options, a test suggests the spec is wrong, or a change would weaken a stated invariant. + +--- + +## Session End + +Before ending a session: + +1. Update the active board Current Status. +2. Add a Work Log entry with what changed, verification, issues, and next step. +3. Update References for every created or modified file. +4. Update Tests with exact commands and results. +5. Update `PROGRESS.md` for the session or accepted phase. +6. Run `git status --short` and `git log --oneline -10`. +7. Commit completed board steps unless the operator explicitly says not to. +8. Tell the operator where the next session picks up. + +If a board marks a step DONE, a matching commit must exist or the uncommitted state must be handed back explicitly. + +--- + +## Source Of Truth + +| Priority | Source | Purpose | +|---|---|---| +| 0 | `AGENTS.md` | Agent operating rules. | +| 1 | `docs/boards/phase_NN_*.md` | Active phase state, issues, references, tests, and work log. | +| 2 | `docs/boards/README.md` | Active phase pointer, phase index, and board template. | +| 3 | `WORKFLOW.md` | Workflow process manual. | +| 4 | `PROGRESS.md` | Historical accepted phase and session archive. | diff --git a/skills/.curated/phasekeeper/assets/templates/PROGRESS.md b/skills/.curated/phasekeeper/assets/templates/PROGRESS.md new file mode 100644 index 00000000..a20592e5 --- /dev/null +++ b/skills/.curated/phasekeeper/assets/templates/PROGRESS.md @@ -0,0 +1,37 @@ +# Progress + +Historical archive of accepted phases and session handoffs. + +Keep this file concise. The active board is the detailed source of truth for current work. + +--- + +## Current + +- Active phase: _(not opened yet)_ +- Active board: `docs/boards/README.md` +- Last session: _(none yet)_ +- Next step: initialize the first phase spec and board + +--- + +## Accepted Phases + +_(No accepted phases yet.)_ + +--- + +## Session Archive + +_(No sessions archived yet.)_ + +Entry format: + +```markdown +### YYYY-MM-DD - Session N +- Phase: NN - +- Completed: +- Verification: +- Issues: +- Next: +``` diff --git a/skills/.curated/phasekeeper/assets/templates/WORKFLOW.md b/skills/.curated/phasekeeper/assets/templates/WORKFLOW.md new file mode 100644 index 00000000..5a8a4add --- /dev/null +++ b/skills/.curated/phasekeeper/assets/templates/WORKFLOW.md @@ -0,0 +1,181 @@ +# Phasekeeper Workflow + +Board-first process for phased work. This file defines how work gets opened, tracked, verified, committed, and handed off. + +Where this file conflicts with `AGENTS.md`, `AGENTS.md` wins. + +--- + +## Lifecycle + +```text +session start + | + v +read docs/boards/README.md + | + v +active board exists? + | + +-- no --> create or approve a phase spec + | | + | v + | create board from template + | + +-- yes --> implementation mode + | + v + pick up next unchecked step + | + v + make scoped change + | + v + run relevant verification + | + v + update board and PROGRESS.md + | + v + commit completed step + | + v + stop at phase gate or wait for continue +``` + +--- + +## Session Start + +Every session starts with these reads, in order: + +1. `docs/boards/README.md` +2. the active board listed there, if it exists +3. the active phase spec listed by the board, if it exists +4. `WORKFLOW.md` +5. any OPEN issues on the active board + +Then report: + +```text +Phase NN, Step K of N. Open issues: N. Next up: . Ready? +``` + +No implementation work starts until the operator confirms. + +--- + +## Spec Mode + +Use spec mode when the next phase is known but no approved spec exists. + +Output: + +```text +docs/specs/phase_NN_.md +``` + +A phase spec should cover: + +- Goal and non-goals +- Scope boundaries +- User-visible behavior or contract changes +- Data model or API changes +- Configuration changes +- Tests and verification gates +- Implementation order +- Open questions + +The spec is not approved until the operator explicitly says it is approved. +When approved, update the spec metadata to `Status: APPROVED` and fill in the approval fields. + +--- + +## Board Creation + +Create a board after the spec is approved and before implementation starts: + +```text +docs/boards/phase_NN_.md +``` + +Use `docs/boards/phase-board.template.md`. Populate: + +- Current status +- Implementation steps from the approved spec +- Open question resolutions +- Gate interpretations +- References +- Issues +- Tests +- Work log +- Deferred issues + +Every issue, decision, and session handoff goes on the board. If it is not on the board, the next session cannot reliably reconstruct it. + +--- + +## Implementation Mode + +Before editing code, read: + +1. active board +2. approved spec +3. every code file the step will touch +4. relevant tests + +For each step: + +1. Confirm the worktree state. +2. Write or update the narrowest relevant test when behavior changes. +3. Implement the minimal scoped change. +4. Run the narrowest relevant verification. +5. Update board references with changed files. +6. Update board tests with commands and results. +7. Update the board work log. +8. Update `PROGRESS.md` after the session or accepted phase. +9. Commit the completed step unless the operator says not to. + +Do not merge unrelated cleanup into a phase step. + +--- + +## Issue Tracking + +Issues live on the active board. + +Use this format: + +```markdown +### ISS-001 - +**Status:** OPEN | **Severity:** high/medium/low | **Found:** Step K, YYYY-MM-DD +**Files:** `path/to/file.py:line` +**What is wrong:** +**How to reproduce:** +**Root cause:** _(filled when diagnosed)_ +**Resolution:** _(filled when fixed or deferred)_ +**Resolved:** _(date + step, or "deferred to Phase NN")_ +``` + +Severity guide: + +- High: blocks the phase, threatens core guarantees, or means the spec may be wrong. Stop and ask. +- Medium: must be resolved before phase completion but does not block the current step. +- Low: non-blocking cleanup or clarity issue. + +--- + +## Session End + +Before ending a session: + +1. Update the board Current Status. +2. Add a Work Log entry with what changed, verification, issues, and next step. +3. Update References for every file created or modified. +4. Update Tests with exact commands and results. +5. Update `PROGRESS.md` for the session or accepted phase. +6. Run `git status --short` and `git log --oneline -10`. +7. Commit completed board steps unless the operator explicitly says not to. +8. Tell the operator the next board step. + +If a board marks a step DONE, a matching commit must exist or the work must be explicitly handed back as uncommitted. diff --git a/skills/.curated/phasekeeper/assets/templates/docs-boards-README.md b/skills/.curated/phasekeeper/assets/templates/docs-boards-README.md new file mode 100644 index 00000000..79f07a9f --- /dev/null +++ b/skills/.curated/phasekeeper/assets/templates/docs-boards-README.md @@ -0,0 +1,27 @@ +# Phasekeeper Board Index + +This is where agents look first every session. Find the active phase, then read the board or create it through `WORKFLOW.md` if it does not exist yet. + +--- + +## Active Phase + +**Phase 01 - ** | Status: NOT OPENED | Spec: _(not approved)_ | Board: _(not created)_ + +Exactly one phase is active. + +--- + +## Phase Index + +| Phase | Spec | Board | Status | +|---|---|---|---| +| 01 - | _(not opened)_ | _(not opened)_ | PLANNED | + +--- + +## Board Template + +When starting implementation of a phase, copy `phase-board.template.md` to `phase_NN_.md` and fill it in. + +Create or update the phase spec first from `docs/specs/phase-spec.template.md`. Only create a board after the operator explicitly approves the spec. diff --git a/skills/.curated/phasekeeper/assets/templates/phase-board.md b/skills/.curated/phasekeeper/assets/templates/phase-board.md new file mode 100644 index 00000000..a58748ee --- /dev/null +++ b/skills/.curated/phasekeeper/assets/templates/phase-board.md @@ -0,0 +1,126 @@ +# Phase NN - + +## Current Status + +Phase state: NOT_STARTED +Step: 0 of N +Branch: +Started: YYYY-MM-DD +Last session: YYYY-MM-DD +Last updated: YYYY-MM-DD +Spec: `docs/specs/phase_NN_.md` + +--- + +## Implementation Steps + +From the approved spec. Check off only after verification and commit or explicit handoff. + +- [ ] Step 1: +- [ ] Step 2: +- [ ] Step 3: + +--- + +## Open Question Resolutions + +_(No resolved questions yet.)_ + +When a spec question is resolved, record it here: + +| # | Decision | Rationale | +|---|---|---| +| Q1 | | | + +--- + +## Gate Interpretations + +Pin any gate whose measurement, time range, fixture set, or aggregation was ambiguous in the spec. + +_(None yet.)_ + +--- + +## References + +Every file this phase creates or modifies. Updated as work happens. + +| File | Change | Step | +|---|---|---| +| `path/to/file.py:line` | | Step K | + +--- + +## Issues + +Log every issue when found. + +_(No issues yet.)_ + + + +--- + +## Tests + +### Per-Step Results + +| Step | Tests | Result | Date | +|---|---|---|---| +| 1 | | PASS/FAIL | YYYY-MM-DD | + +### Final Gate + +- [ ] Narrow relevant tests pass +- [ ] Full relevant test suite passes when feasible +- [ ] Static checks pass when configured +- [ ] `git diff --check` passes +- [ ] All OPEN issues are resolved or explicitly deferred +- [ ] Phase Summary filled in +- [ ] `PROGRESS.md` updated + +--- + +## Work Log + +Reverse chronological. Log every session. + +### YYYY-MM-DD - Session N + +- Resumed at step K. +- Completed: . +- Issues found: . +- Tests: . +- Next: step K+1 - . + +--- + +## Deferred Issues + +_(None yet.)_ + +--- + +## Phase Summary + +_(Filled in when phase is complete.)_ + +### What shipped vs spec + +- Built as specified: +- Deferred: +- Added beyond spec: + +### Lessons for downstream phases + +- diff --git a/skills/.curated/phasekeeper/assets/templates/phase-spec.md b/skills/.curated/phasekeeper/assets/templates/phase-spec.md new file mode 100644 index 00000000..3941190a --- /dev/null +++ b/skills/.curated/phasekeeper/assets/templates/phase-spec.md @@ -0,0 +1,51 @@ +# Phase NN - Spec + +Status: DRAFT +Approved by: _(not approved)_ +Approved at: _(not approved)_ +Board: _(not created)_ + +Do not change `Status` to `APPROVED` until the operator explicitly approves this spec. + +--- + +## Goal + +Describe the single outcome this phase must deliver. + +## Non-Goals + +- List work that is explicitly out of scope. + +## Scope Boundaries + +- Files, modules, or workflows this phase may touch. +- Files, modules, or workflows this phase must not touch. + +## Behavior and Contract Changes + +- User-visible behavior changes. +- API, schema, model, or data contract changes. +- Migration or compatibility requirements. + +## Configuration + +- New configuration values. +- Changed defaults. +- Environment variables. + +## Tests and Verification Gates + +- Narrow tests required during implementation. +- Full-suite or integration checks required before phase completion. +- Manual verification, if any. + +## Implementation Order + +1. +2. +3. + +## Open Questions + +- Q1: diff --git a/skills/.curated/phasekeeper/scripts/init_phasekeeper.py b/skills/.curated/phasekeeper/scripts/init_phasekeeper.py new file mode 100755 index 00000000..06c960a4 --- /dev/null +++ b/skills/.curated/phasekeeper/scripts/init_phasekeeper.py @@ -0,0 +1,82 @@ +#!/usr/bin/env python3 +from __future__ import annotations + +import argparse +from dataclasses import dataclass +from pathlib import Path + + +ROOT = Path(__file__).resolve().parents[1] +TEMPLATE_ROOT = ROOT / "assets" / "templates" + + +@dataclass(frozen=True) +class TemplateFile: + source: str + destination: str + + +TEMPLATE_FILES = ( + TemplateFile("AGENTS.md", "AGENTS.md"), + TemplateFile("WORKFLOW.md", "WORKFLOW.md"), + TemplateFile("PROGRESS.md", "PROGRESS.md"), + TemplateFile("docs-boards-README.md", "docs/boards/README.md"), + TemplateFile("phase-board.md", "docs/boards/phase-board.template.md"), + TemplateFile("phase-spec.md", "docs/specs/phase-spec.template.md"), +) + + +def parse_args() -> argparse.Namespace: + parser = argparse.ArgumentParser( + description="Scaffold Phasekeeper workflow files into a repository." + ) + parser.add_argument( + "target", + nargs="?", + default=".", + help="Repository root to initialize. Defaults to the current directory.", + ) + parser.add_argument( + "--force", + action="store_true", + help="Overwrite existing workflow files.", + ) + return parser.parse_args() + + +def copy_template(target_root: Path, template_file: TemplateFile, *, force: bool) -> str: + source = TEMPLATE_ROOT / template_file.source + destination = target_root / template_file.destination + existed = destination.exists() + + if existed and not force: + return f"SKIPPED {template_file.destination} (already exists)" + + destination.parent.mkdir(parents=True, exist_ok=True) + content = source.read_text(encoding="utf-8") + destination.write_text(content, encoding="utf-8") + + if existed and force: + return f"OVERWROTE {template_file.destination}" + return f"CREATED {template_file.destination}" + + +def init_phasekeeper(target: Path, *, force: bool) -> list[str]: + target_root = target.resolve() + target_root.mkdir(parents=True, exist_ok=True) + return [ + copy_template(target_root, template_file, force=force) + for template_file in TEMPLATE_FILES + ] + + +def main() -> int: + args = parse_args() + messages = init_phasekeeper(Path(args.target), force=args.force) + for message in messages: + print(message) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) From adf9f4da566a13fe4f3c091d5a2349ec21a7d9b7 Mon Sep 17 00:00:00 2001 From: Deepak Date: Tue, 5 May 2026 01:13:39 +0530 Subject: [PATCH 2/3] Soften Phasekeeper commit guidance --- skills/.curated/phasekeeper/SKILL.md | 6 +++--- skills/.curated/phasekeeper/assets/templates/AGENTS.md | 2 +- skills/.curated/phasekeeper/assets/templates/WORKFLOW.md | 6 +++--- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/skills/.curated/phasekeeper/SKILL.md b/skills/.curated/phasekeeper/SKILL.md index f3847470..d49a5f69 100644 --- a/skills/.curated/phasekeeper/SKILL.md +++ b/skills/.curated/phasekeeper/SKILL.md @@ -104,7 +104,7 @@ For each active step: 5. Run relevant verification. 6. Update board References, Tests, Issues, and Work Log. 7. Update `PROGRESS.md` after the session or accepted phase. -8. Commit completed board steps unless the operator says not to. +8. Commit completed board steps only when repo policy or the operator has already authorized commits; otherwise hand back the completed uncommitted work explicitly. Do not mix unrelated cleanup into a phase step. @@ -121,10 +121,10 @@ Before final response: 5. Update `PROGRESS.md`. 6. Run `git status --short`. 7. Run `git log --oneline -10`. -8. Commit completed board steps unless the operator says not to. +8. Commit completed board steps only when repo policy or the operator has already authorized commits; otherwise hand back the completed uncommitted work explicitly. 9. Tell the operator exactly where the next session picks up. -If a board marks a step DONE but no matching commit exists, say so explicitly. +If a board marks a step DONE but no matching commit exists, document the explicit uncommitted handoff. ## Hard Stops diff --git a/skills/.curated/phasekeeper/assets/templates/AGENTS.md b/skills/.curated/phasekeeper/assets/templates/AGENTS.md index c191b3e3..39b3835d 100644 --- a/skills/.curated/phasekeeper/assets/templates/AGENTS.md +++ b/skills/.curated/phasekeeper/assets/templates/AGENTS.md @@ -47,7 +47,7 @@ Before ending a session: 4. Update Tests with exact commands and results. 5. Update `PROGRESS.md` for the session or accepted phase. 6. Run `git status --short` and `git log --oneline -10`. -7. Commit completed board steps unless the operator explicitly says not to. +7. Commit completed board steps only when repo policy or the operator has already authorized commits; otherwise hand back the completed uncommitted work explicitly. 8. Tell the operator where the next session picks up. If a board marks a step DONE, a matching commit must exist or the uncommitted state must be handed back explicitly. diff --git a/skills/.curated/phasekeeper/assets/templates/WORKFLOW.md b/skills/.curated/phasekeeper/assets/templates/WORKFLOW.md index 5a8a4add..14ebe19b 100644 --- a/skills/.curated/phasekeeper/assets/templates/WORKFLOW.md +++ b/skills/.curated/phasekeeper/assets/templates/WORKFLOW.md @@ -37,7 +37,7 @@ active board exists? update board and PROGRESS.md | v - commit completed step + commit or hand off completed step | v stop at phase gate or wait for continue @@ -134,7 +134,7 @@ For each step: 6. Update board tests with commands and results. 7. Update the board work log. 8. Update `PROGRESS.md` after the session or accepted phase. -9. Commit the completed step unless the operator says not to. +9. Commit the completed step only when repo policy or the operator has already authorized commits; otherwise hand back the completed uncommitted work explicitly. Do not merge unrelated cleanup into a phase step. @@ -175,7 +175,7 @@ Before ending a session: 4. Update Tests with exact commands and results. 5. Update `PROGRESS.md` for the session or accepted phase. 6. Run `git status --short` and `git log --oneline -10`. -7. Commit completed board steps unless the operator explicitly says not to. +7. Commit completed board steps only when repo policy or the operator has already authorized commits; otherwise hand back the completed uncommitted work explicitly. 8. Tell the operator the next board step. If a board marks a step DONE, a matching commit must exist or the work must be explicitly handed back as uncommitted. From 977d3e17e7441a4e0f333cdb23e1b580f9e879c5 Mon Sep 17 00:00:00 2001 From: Deepak Date: Tue, 5 May 2026 01:17:55 +0530 Subject: [PATCH 3/3] Tighten Phasekeeper trigger description --- skills/.curated/phasekeeper/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/.curated/phasekeeper/SKILL.md b/skills/.curated/phasekeeper/SKILL.md index d49a5f69..67a2fafa 100644 --- a/skills/.curated/phasekeeper/SKILL.md +++ b/skills/.curated/phasekeeper/SKILL.md @@ -1,6 +1,6 @@ --- name: phasekeeper -description: Use when setting up or operating a Phasekeeper workflow for Codex projects with active phase boards, approved specs, session start gates, issue tracking, verification logs, progress archives, and clean handoffs. +description: Use when installing, starting, resuming, or closing a Phasekeeper-managed Codex project that uses board-first phase tracking, verification logs, and explicit handoffs. metadata: short-description: Board-first workflow for long-running Codex projects ---