Home/ai-coding-skills
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Perform code optimization and document cleanup (#1)
check / check (ubuntu-latest) (push) Successful in 2m5s
Details
check / check (macos-latest) (push) Has been cancelled
Details
check-online / check-online (ubuntu-latest) (push) Successful in 1m53s
Details

Browse Source 
## Summary
- add repository-wide quality tooling and verification scaffolding, including CI workflows, pnpm workspace setup, ESLint/Prettier/markdown checks, and generated-output verification helpers
- reorganize skill sources and generation flow by introducing canonical `_source` variants, generator/manifests, reusable helper abstractions, and shared web-automation/browser utilities
- clean up and expand documentation so the root README flows into docs and skill docs, with clearer development, reviewer, installer, and workflow guidance

## Notable changes
- docs flow and consistency cleanup across `README.md`, `docs/README.md`, and related docs
- new scripts for `check`, docs verification, generated-file verification, shell portability, and safe directory replacement
- refactors in Atlassian and web-automation skill runtimes to reduce duplication and centralize reusable code
- changelog, development documentation, and CI surface updates

## Test Plan
- [ ] `pnpm run check`
- [ ] review generated/manifests and skill sync outputs
- [ ] smoke-check docs flow from `README.md` to `docs/README.md` to skill docs

## Notes
- this branch currently includes tracked `skills/web-automation/shared/node_modules` content that should be reviewed carefully as potentially noisy/accidental committed artifacts

Co-authored-by: Stefano Fiorini <stefano.fiorini@firsthorizon.com>
Reviewed-on: #1
This commit was merged in pull request #1.
This commit is contained in:
Stefano Fiorini
2026-05-04 04:41:34 +00:00
parent 2deab1c1b4
commit 251148c3ff
373 changed files with 28504 additions and 1281 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/do-task/_source/pi/SKILL.md
+210
View File
@@ -0,0 +1,210 @@
---
name: do-task
description: Execute a single user-supplied prompt end-to-end in pi with plan review, implementation review, verification, and one persistent task-plan artifact.
---
# Do Task (Pi)
Execute an ad-hoc user prompt end-to-end: parse, clarify, plan, implement, verify, review, commit, and optionally push.
This variant uses one persistent `task-plan.md` under `ai_plan/` and defaults to the current branch unless the prompt explicitly opts into a worktree workflow.
## Shared Setup
Before using this skill, read:
- [docs/PI-SUPERPOWERS.md](../../../docs/PI-SUPERPOWERS.md)
- [docs/PI-COMMON-REVIEWER.md](../../../docs/PI-COMMON-REVIEWER.md)
This workflow depends on:
- Superpowers skills being visible to pi
- the pi reviewer-runtime helper being installed in a supported location
## Prerequisite Check (MANDATORY)
Required:
- `pi --version`
- Superpowers `brainstorming`
- Superpowers `test-driven-development`
- Superpowers `verification-before-completion`
- Superpowers `finishing-a-development-branch`
- Superpowers `using-git-worktrees` when the prompt opts into a worktree
- pi reviewer runtime helper
- pi Telegram notifier helper
Quick checks for common installs:
```bash
pi --version
test -f ~/.agents/skills/superpowers/brainstorming/SKILL.md || test -f ~/.pi/agent/skills/superpowers/brainstorming/SKILL.md
test -f ~/.agents/skills/superpowers/test-driven-development/SKILL.md || test -f ~/.pi/agent/skills/superpowers/test-driven-development/SKILL.md
test -f ~/.agents/skills/superpowers/verification-before-completion/SKILL.md || test -f ~/.pi/agent/skills/superpowers/verification-before-completion/SKILL.md
test -f ~/.agents/skills/superpowers/finishing-a-development-branch/SKILL.md || test -f ~/.pi/agent/skills/superpowers/finishing-a-development-branch/SKILL.md
test -x .pi/skills/reviewer-runtime/pi/run-review.sh || test -x ~/.pi/agent/skills/reviewer-runtime/pi/run-review.sh
test -x .pi/skills/reviewer-runtime/pi/notify-telegram.sh || test -x ~/.pi/agent/skills/reviewer-runtime/pi/notify-telegram.sh
```
If you use a settings-defined skill path for Superpowers, confirm it matches [docs/PI-SUPERPOWERS.md](../../../docs/PI-SUPERPOWERS.md) before continuing.
If you install the reviewer helper in a nonstandard location, confirm it matches [docs/PI-COMMON-REVIEWER.md](../../../docs/PI-COMMON-REVIEWER.md) before continuing.
If any required dependency is missing, stop immediately and return:
`Missing dependency: pi do-task requires the workflow skills and reviewer setup documented in docs/PI-SUPERPOWERS.md and docs/PI-COMMON-REVIEWER.md.`
## Required Workflow Rules
- Load the relevant workflow skill before entering its phase. If pi did not auto-load it, use `/skill:<name>`.
- Announce skill usage explicitly:
- `I've read the [Skill Name] skill and I'm using it to [purpose].`
- Keep the `task-plan.md` artifact current as work progresses.
- Do not use deprecated wrapper CLIs.
## Trigger Detection
Always use this skill for:
- `/do-task`
- `do this task`
- `do task ...`
- `execute this task`
- `make it so`
- `just do ...` when another skill is not a better fit
Use current-branch execution by default. Only switch to a worktree when the prompt explicitly asks for one.
## Process
### Phase 1: Preflight
1. Verify the repo: `git rev-parse --is-inside-work-tree`
2. Ensure `/ai_plan/` exists in `.gitignore`
3. Confirm the required workflow skills are available to pi
4. Announce each workflow skill before using it
### Phase 2: Parse Prompt And Clarify
1. Capture the user's prompt verbatim
2. Detect whether the prompt is concrete enough to proceed without questions
3. If needed, ask 1-3 short questions one at a time
4. Load `brainstorming` for behavior-changing work unless the task is pure documentation or pure comment/whitespace/rename work
### Phase 3: Configure Reviewer
If the user already specified reviewer settings, use them. Otherwise ask:
Reviewer CLI: `codex`, `claude`, `cursor`, `opencode`, `pi`, or `skip`
1. Which CLI should review the plan and implementation?
2. Reviewer model
3. Max rounds, default `10`
Store `REVIEWER_CLI`, `REVIEWER_MODEL`, and `MAX_ROUNDS`.
If `REVIEWER_CLI=pi`, verify the Pi reviewer binary before entering the review loop:
```bash
pi --version
```
For shorthand `pi/<pi-model-name>`, split only on the first slash when the prefix is exactly `pi`; store the complete remainder in `REVIEWER_MODEL`. Examples: `pi/claude-opus-4-7` -> `claude-opus-4-7`, `pi/anthropic/claude-opus-4-7` -> `anthropic/claude-opus-4-7`, and `pi/openrouter/anthropic/claude-opus-4-7` -> `openrouter/anthropic/claude-opus-4-7`.
When `REVIEWER_CLI=pi`, the reviewer model is configured independently from the pi model running this workflow. Use any configured pi model string, including provider-qualified model IDs. If the reviewer model or provider is unavailable, surface the review helper stderr/status and ask for a configured model; use `pi --list-models [search]` to inspect configured models.
The pi reviewer command rendered into `/tmp/do-task-${REVIEW_KIND}-review-${REVIEW_ID}.sh` must be isolated and read-only:
```bash
pi --no-session --no-skills --no-prompt-templates --no-extensions --no-context-files --model "$REVIEWER_MODEL" --tools read,grep,find,ls -p "Read the file /tmp/do-task-${REVIEW_KIND}-${REVIEW_ID}.md and review."
```
The pi reviewer invocation must not load workflow skills and must not include `write`, `edit`, or `bash` tools.
### Phase 4: Initialize `task-plan.md`
1. Compute `ai_plan/YYYY-MM-DD-<slug>/`
2. Resume if an existing plan folder is active, otherwise create a new one
3. Write `task-plan.md` from this skill's `templates/task-plan.md`
4. Fill `Metadata`, `Prompt`, `Interpretation`, `Assumptions`, `Files`, `Approach`, `TDD Approach`, `Acceptance Criteria`, `Verification`, and `Rollback`
5. Set `Status: draft`
If the prompt explicitly opts into a worktree, load `using-git-worktrees` before implementation. Otherwise remain on the current branch.
### Phase 5: Plan Review Loop
Skip this phase if `REVIEWER_CLI=skip`.
1. Write a reviewer payload from `task-plan.md`
2. Strip the runtime-only sections before sending it out
3. Run the reviewer through the pi reviewer-runtime helper when available
4. Fix `P0`, `P1`, and `P2` findings before proceeding
5. Keep `P3` findings for optional cleanup
6. Set `Status: plan-approved` when the reviewer approves
The reviewer response format must be:
```text
## Summary
...
## Findings
### P0
- ...
### P1
- ...
### P2
- ...
### P3
- ...
## Verdict
VERDICT: APPROVED
```
### Phase 6: Execute
1. Set `Status: implementation-in-progress`
2. Load `test-driven-development` for every behavior-changing edit unless `task-plan.md` explicitly records an allowed skip
3. Update `task-plan.md` as acceptance criteria are completed
4. Do not commit yet
### Phase 7: Verification Gate
1. Load `verification-before-completion`
2. Run the commands listed in `task-plan.md`
3. Fix failures and re-run verification until green
4. If verification stalls repeatedly, stop and surface the blocker
### Phase 8: Implementation Review Loop
Skip this phase if `REVIEWER_CLI=skip`.
1. Build a review payload from the approved plan, current diff, and verification output
2. Run the reviewer through the pi reviewer-runtime helper
3. Address `P0`, `P1`, and `P2` findings before approval
4. Fix cheap `P3` findings when safe
5. Set `Status: implementation-approved` when approved
### Phase 9: Commit And Push Decision
1. Load `finishing-a-development-branch`
2. Stage only the intended files
3. Create one commit for the task
4. Ask whether to push or keep the work local
### Phase 10: Telegram Completion Notification
Resolve the helper in this order:
```bash
TELEGRAM_NOTIFY_RUNTIME=""
for candidate in ".pi/skills/reviewer-runtime/pi/notify-telegram.sh" "$HOME/.pi/agent/skills/reviewer-runtime/pi/notify-telegram.sh"; do
if [ -x "$candidate" ]; then
TELEGRAM_NOTIFY_RUNTIME="$candidate"
break
fi
done
```
If the helper exists and both `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID` are configured, send a short completion summary. Otherwise state that no Telegram completion notification was sent.