ASI Enhance Skill

skills/asi-enhance/README.md

@@ -0,0 +1,27 @@
+# ASI Enhance
+
+`asi-enhance` now produces deterministic, phased plans much like the workplan skill did for developer. The new generator (`scripts/generate_plan.py`) reads `plans/workplan.json`, renders `WORKPLAN.md`, and writes `execution/phase_progress.json` plus the structured context file `execution/next_task_context.json`. The helper script (`scripts/phase-helper.sh`) invokes the generator before execution, returns the next task context after each completion, and can emit the current task context on demand so downstream skills receive the right context without re-reading the entire plan.
+
+## Workflow
+
+1. Update `plans/workplan.json` with the desired phases, tasks, commands, and verification entries for this enhancement.
+2. Run `python3 scripts/generate_plan.py --definition plans/workplan.json --output WORKPLAN.md --progress execution/phase_progress.json` to create the plan and tracker.
+3. Before running `execute-plan.sh`, call `./scripts/phase-helper.sh ensure-plan --definition plans/workplan.json --plan WORKPLAN.md --progress execution/phase_progress.json` (the master workflow automatically includes this invocation).
+4. After each completed task, run `./scripts/phase-helper.sh next-task --plan WORKPLAN.md --progress execution/phase_progress.json --task <id> --output execution/next_task_context.json` to capture the structured context for the next task.
+5. When you need to preview the currently active or next task without advancing the tracker, run `./scripts/phase-helper.sh current-task --progress execution/phase_progress.json --output execution/next_task_context.json`; it emits the same structured JSON message that downstream agents read to minimize context rot.
+
+## Artifacts
+
+- `plans/workplan.json` – defines each phase/task plus commands/verification/metadata.
+- `WORKPLAN.md` – generated plan consumed by the developer skill, containing the new metadata block referencing `asi-enhance`.
+- `execution/phase_progress.json` – records the current phase/task status.
+- `execution/next_task_context.json` – structured JSON with the next task’s summary, commands, verification, and phase context.
+
+## Command checklist
+
+-- `./scripts/generate_plan.py --definition plans/workplan.json --output WORKPLAN.md --progress execution/phase_progress.json`
+-- `./scripts/phase-helper.sh ensure-plan --definition plans/workplan.json --plan WORKPLAN.md --progress execution/phase_progress.json`
+- `./scripts/phase-helper.sh next-task --plan WORKPLAN.md --progress execution/phase_progress.json --task <id>`
+- `./scripts/phase-helper.sh current-task --progress execution/phase_progress.json`
+
+Document your decisions in `references/QUESTIONS.md`, follow the guard scripts from `references/command-checklist.md`, and keep the ASI paradigms from `references/09_PARADIGMS.md` in mind.

skills/asi-enhance/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: asi-enhance
+description: Enhance an existing skill into an ASI-aligned structure with stronger reliability, performance, and security. Use when you need to upgrade, harden, or refactor a skill (including an existing ASI skill), produce enhancement artifacts, or standardize a skill's structure, scripts, references, and validation workflow.
+---
+
+# INSTRUCTIONS
+
+1. Confirm the skill path, run `scripts/init.sh --skill-path "<path>"` (it defaults to `<path>/.asi/enhance`), then run `python3 scripts/scan_skill.py --skill-path "<path>"` so you can review `<path>/.asi/enhance/STATE.json`, `INVENTORY.json`, and `SCAN.md` before moving forward.
+2. Read `references/09_PARADIGMS.md` for the target paradigms, positive patterns, anti-patterns, and supporting references you should bring to every enhancement, then consult `references/00_ROUTER.md` and choose a route.  Already-ASI targets should read `01_SUMMARY.md`, `04_NEVER.md`, `05_ALWAYS.md`, `06_PROCEDURE.md`, and `08_CHECKLISTS.md`; conversions also read `02_CONTRACTS.md`; enhancement-only requests can focus on `01_SUMMARY.md`, `05_ALWAYS.md`, `06_PROCEDURE.md`, and `08_CHECKLISTS.md`.  Capture the chosen route inside `<path>/.asi/enhance/ENHANCEMENT_REPORT.md`.
+3. When documenting remote access guidance for another repo, include instructions that show how to call `../librarian/scripts/<tool>` directly, which `--root`/`--db` flags to use, and which logs (`execution/index.log`, `execution/verify.log`, `execution/purge.log`) capture the actions you just ran.
+4. When working on `developer`, include the explicit commands flagged by `references/command-checklist.md` (validate-plan, check-workspace, check-anti-patterns) so agents always supply `--plan`, `--required`, `--approval-pattern`, and the correct `--root` for their repo before running the script.
+5. Use `<path>/.asi/enhance/ENHANCEMENT_REPORT.md` (template in `assets/templates/ENHANCEMENT_REPORT.template.md`) and `<path>/.asi/enhance/CHANGELOG_ENTRY.md` to document gaps, proposed reliability/performance/security mitigation steps, and acceptance criteria; keep the report in sync as you refine the plan.
+6. Do not edit the target skill until the plan is approved; behavior-driving or destructive changes require explicit user approval or a hand-off to `asi-exec`, and every sensitive operation must be logged in the enhancement report per `references/04_NEVER.md` and `references/02_CONTRACTS.md`.
+7. Use `scripts/phase-helper.sh ensure-plan --definition plans/workplan.json --plan WORKPLAN.md --progress execution/phase_progress.json` before running tasks and let the helper emit `execution/next_task_context.json` via `scripts/phase-helper.sh next-task --task <id>` after each completion so the structured context remains current.
+7. After implementing approved changes, rerun `python3 scripts/scan_skill.py --skill-path "<path>"`, refresh the report with validation notes, and confirm the changelog plus checklist entries reflect the updated state before closing the enhancement.

skills/asi-enhance/WORKPLAN.md

@@ -0,0 +1,75 @@
+# WORKPLAN — asi-enhance skill
+
+## Plan Metadata
+Approval pattern: ^Approved:[[:space:]]+yes$
+Required sections: Intent,Goals,Non-Goals,Scope,Constraints,Plan,Commands,Validation,Approval
+Validation policy: explicit commands (guard scripts + scans)
+Plan Source: asi-enhance
+Plan Definition: plans/workplan.json
+Phase progress file: execution/phase_progress.json
+
+## Intent
+Formalize the new asi-enhance workflow with phased planning and structured context for each enhancement task.
+
+## Goals
+- Document the new generator/TRACKER flow so authors know how to run it.
+- Produce phased plans plus a phase tracker for enhancement tasks.
+- Ensure the helper exposes the next task context for the developer skill.
+
+## Non-Goals
+- Execute commands without a plan approval.
+- Replace external scripts such as workplan or developer.
+
+## Scope
+- Generate WORKPLAN.md from this definition.
+- Emit execution/phase_progress.json and execution/next_task_context.json.
+- Document the helper script that developers call after each completed task.
+
+## Constraints
+- Plans must include the required metadata block (Intent → Approval).
+- Phase tracker must remain under execution/.
+- Helper output must remain deterministic and auditable.
+
+## Plan
+### Phase 1 — Document the pipeline
+Describe how asi-enhance now uses the generator/helper/progress tracker before enhancing a skill.
+- [ ] T001: Clarify the new README and SKILL guidance to mention the phased plan definition and tracker.
+  Update README.md, SKILL.md, and references to describe the generator, the
+  helper, and the synchronized context files.
+  Commands:
+  - rg -n "workplan.json" README.md SKILL.md references/*.md
+  Verification:
+  - python3 scripts/ensure_workplan_artifacts.py --definition plans/workplan.json --plan WORKPLAN.md --progress execution/phase_progress.json
+
+### Phase 2 — Implement the generator/tracker
+Add scripts that render WORKPLAN.md from the definition and update the progress file.
+- [ ] T002: Create scripts/generate_plan.py and scripts/update_phase_progress.py plus the phase definition.
+  Ensure they stay deterministic, include metadata field references, and output
+  `execution/next_task_context.json` when returning the next task.
+  Commands:
+  - python3 scripts/ensure_workplan_artifacts.py --definition plans/workplan.json --plan WORKPLAN.md --progress execution/phase_progress.json
+  Verification:
+  - cat execution/phase_progress.json
+
+### Phase 3 — Helper integration
+Expose scripts/phase-helper.sh so execute-plan runs workplan-like next-task queries.
+- [ ] T003: Add scripts/phase-helper.sh and update documentation so the helper runs before/after tasks.
+  The helper should regenerate the plan if needed and emit the next task context
+  after updates.
+  Commands:
+  - ./scripts/phase-helper.sh ensure-plan --plan ./WORKPLAN.md --progress execution/phase_progress.json
+  Verification:
+  - ./scripts/phase-helper.sh next-task --plan ./WORKPLAN.md --progress execution/phase_progress.json --task T001 --output execution/next_task_context.json
+
+## Commands
+- python3 scripts/ensure_workplan_artifacts.py --definition plans/workplan.json --plan WORKPLAN.md --progress execution/phase_progress.json
+- ./scripts/phase-helper.sh ensure-plan --definition plans/workplan.json --plan ./WORKPLAN.md --progress execution/phase_progress.json
+
+## Validation
+- ./scripts/validate-plan.sh --plan ./WORKPLAN.md --required "Intent,Goals,Non-Goals,Scope,Constraints,Plan,Commands,Validation,Approval" --approval-pattern "^Approved:[[:space:]]+yes$"
+- ./scripts/check-workspace.sh --root . --fail-on-dirty
+
+## Approval
+Approved: yes
+Approved by: bsmith
+Approved on: 2026-01-28

skills/asi-enhance/assets/templates/CHANGELOG_ENTRY.template.md

@@ -0,0 +1,6 @@
+## [Unreleased]
+
+- Enhancement:
+- Reliability:
+- Performance:
+- Security:

skills/asi-enhance/assets/templates/ENHANCEMENT_REPORT.template.md

@@ -0,0 +1,52 @@
+# Enhancement Report
+
+## Target
+
+- Skill path:
+- Skill name:
+- Scan timestamp (UTC):
+- Scope:
+
+## Current State Summary
+
+- Structure status:
+- Key gaps:
+- Existing strengths:
+
+## Reliability
+
+- Risks:
+- Proposed mitigations:
+- Validation strategy:
+
+## Performance
+
+- Bottlenecks:
+- Proposed improvements:
+- Expected impact:
+
+## Security
+
+- Risks:
+- Proposed hardening:
+- Sensitive operations:
+
+## ASI Alignment
+
+- Artifacts created:
+- Gating/approval points:
+- Open questions:
+
+## Proposed Changes
+
+- Structural changes:
+- Content changes:
+- Script changes:
+- Reference changes:
+
+## Acceptance Criteria
+
+- [ ] No regressions in existing behavior
+- [ ] Required artifacts present
+- [ ] Validation steps documented
+- [ ] Security review completed

skills/asi-enhance/execution/next_task_context.json

@@ -0,0 +1,79 @@
+{
+  "phase_progress": {
+    "plan_definition": "plans/workplan.json",
+    "plan_path": "/Users/bsmith/.codex/skills/asi-enhance/WORKPLAN.md",
+    "phase_index": 0,
+    "task_index": 0,
+    "phases": [
+      {
+        "name": "Phase 1 \u2014 Document the pipeline",
+        "summary": "Describe how asi-enhance now uses the generator/helper/progress tracker before enhancing a skill.",
+        "tasks": [
+          {
+            "id": "T001",
+            "summary": "Clarify the new README and SKILL guidance to mention the phased plan definition and tracker.",
+            "description": "Update README.md, SKILL.md, and references to describe the generator, the helper, and the synchronized context files.",
+            "commands": [
+              "rg -n \"workplan.json\" README.md SKILL.md references/*.md"
+            ],
+            "verification": [
+              "python3 scripts/ensure_workplan_artifacts.py --definition plans/workplan.json --plan WORKPLAN.md --progress execution/phase_progress.json"
+            ],
+            "status": "current"
+          }
+        ]
+      },
+      {
+        "name": "Phase 2 \u2014 Implement the generator/tracker",
+        "summary": "Add scripts that render WORKPLAN.md from the definition and update the progress file.",
+        "tasks": [
+          {
+            "id": "T002",
+            "summary": "Create scripts/generate_plan.py and scripts/update_phase_progress.py plus the phase definition.",
+            "description": "Ensure they stay deterministic, include metadata field references, and output `execution/next_task_context.json` when returning the next task.",
+            "commands": [
+              "python3 scripts/ensure_workplan_artifacts.py --definition plans/workplan.json --plan WORKPLAN.md --progress execution/phase_progress.json"
+            ],
+            "verification": [
+              "cat execution/phase_progress.json"
+            ],
+            "status": "pending"
+          }
+        ]
+      },
+      {
+        "name": "Phase 3 \u2014 Helper integration",
+        "summary": "Expose scripts/phase-helper.sh so execute-plan runs workplan-like next-task queries.",
+        "tasks": [
+          {
+            "id": "T003",
+            "summary": "Add scripts/phase-helper.sh and update documentation so the helper runs before/after tasks.",
+            "description": "The helper should regenerate the plan if needed and emit the next task context after updates.",
+            "commands": [
+              "./scripts/phase-helper.sh ensure-plan --plan ./WORKPLAN.md --progress execution/phase_progress.json"
+            ],
+            "verification": [
+              "./scripts/phase-helper.sh next-task --plan ./WORKPLAN.md --progress execution/phase_progress.json --task T001 --output execution/next_task_context.json"
+            ],
+            "status": "pending"
+          }
+        ]
+      }
+    ]
+  },
+  "current_task": {
+    "id": "T001",
+    "summary": "Clarify the new README and SKILL guidance to mention the phased plan definition and tracker.",
+    "description": "Update README.md, SKILL.md, and references to describe the generator, the helper, and the synchronized context files.",
+    "commands": [
+      "rg -n \"workplan.json\" README.md SKILL.md references/*.md"
+    ],
+    "verification": [
+      "python3 scripts/ensure_workplan_artifacts.py --definition plans/workplan.json --plan WORKPLAN.md --progress execution/phase_progress.json"
+    ],
+    "phase": "Phase 1 \u2014 Document the pipeline",
+    "phase_summary": "Describe how asi-enhance now uses the generator/helper/progress tracker before enhancing a skill.",
+    "phase_index": 0,
+    "task_index": 0
+  }
+}

skills/asi-enhance/execution/phase_progress.json

@@ -0,0 +1,62 @@
+{
+  "plan_definition": "plans/workplan.json",
+  "plan_path": "/Users/bsmith/.codex/skills/asi-enhance/WORKPLAN.md",
+  "phase_index": 0,
+  "task_index": 0,
+  "phases": [
+    {
+      "name": "Phase 1 \u2014 Document the pipeline",
+      "summary": "Describe how asi-enhance now uses the generator/helper/progress tracker before enhancing a skill.",
+      "tasks": [
+        {
+          "id": "T001",
+          "summary": "Clarify the new README and SKILL guidance to mention the phased plan definition and tracker.",
+          "description": "Update README.md, SKILL.md, and references to describe the generator, the helper, and the synchronized context files.",
+          "commands": [
+            "rg -n \"workplan.json\" README.md SKILL.md references/*.md"
+          ],
+          "verification": [
+            "python3 scripts/ensure_workplan_artifacts.py --definition plans/workplan.json --plan WORKPLAN.md --progress execution/phase_progress.json"
+          ],
+          "status": "current"
+        }
+      ]
+    },
+    {
+      "name": "Phase 2 \u2014 Implement the generator/tracker",
+      "summary": "Add scripts that render WORKPLAN.md from the definition and update the progress file.",
+      "tasks": [
+        {
+          "id": "T002",
+          "summary": "Create scripts/generate_plan.py and scripts/update_phase_progress.py plus the phase definition.",
+          "description": "Ensure they stay deterministic, include metadata field references, and output `execution/next_task_context.json` when returning the next task.",
+          "commands": [
+            "python3 scripts/ensure_workplan_artifacts.py --definition plans/workplan.json --plan WORKPLAN.md --progress execution/phase_progress.json"
+          ],
+          "verification": [
+            "cat execution/phase_progress.json"
+          ],
+          "status": "pending"
+        }
+      ]
+    },
+    {
+      "name": "Phase 3 \u2014 Helper integration",
+      "summary": "Expose scripts/phase-helper.sh so execute-plan runs workplan-like next-task queries.",
+      "tasks": [
+        {
+          "id": "T003",
+          "summary": "Add scripts/phase-helper.sh and update documentation so the helper runs before/after tasks.",
+          "description": "The helper should regenerate the plan if needed and emit the next task context after updates.",
+          "commands": [
+            "./scripts/phase-helper.sh ensure-plan --plan ./WORKPLAN.md --progress execution/phase_progress.json"
+          ],
+          "verification": [
+            "./scripts/phase-helper.sh next-task --plan ./WORKPLAN.md --progress execution/phase_progress.json --task T001 --output execution/next_task_context.json"
+          ],
+          "status": "pending"
+        }
+      ]
+    }
+  ]
+}