@pi-unipi/workflow 0.1.7 → 0.1.9

package/skills/chore-create/SKILL.md

@@ -0,0 +1,313 @@
+---
+name: chore-create
+description: "Create reusable chore — save repeatable tasks like deploy, publish, push to docs/chore/."
+---
+
+# Creating Chores
+
+Create reusable chore definitions for repeatable tasks. Save to `.unipi/docs/chore/` for future execution.
+
+## Boundaries
+
+**This skill MAY:** read codebase, ask questions, write chore to `.unipi/docs/chore/`.
+**This skill MAY NOT:** edit code, execute the chore, run tests, deploy.
+
+**This is definition only — not execution.**
+
+## Command Format
+
+```
+/unipi:chore-create <string(greedy)>
+```
+
+- `string(greedy)` — description of the chore to create (e.g., "push to github main", "publish npm package")
+- Write-only sandbox (`.unipi/docs/chore/`)
+
+## Output Path
+
+```
+.unipi/docs/chore/<chore-name>.md
+```
+
+---
+
+## Process
+
+### Phase 1: Understand the Chore
+
+1. Read the chore description
+2. Ask clarifying questions (one at a time):
+   - "What are the exact steps for this chore?"
+   - "Any pre-conditions before running?"
+   - "What should happen if a step fails?"
+   - "Is this interactive or fully automated?"
+
+3. Determine chore type:
+   - **Deploy** — push to production/staging
+   - **Publish** — npm, pypi, docker registry
+   - **Git** — push, merge, release
+   - **Build** — compile, bundle, package
+   - **Test** — run specific test suites
+   - **Maintenance** — cleanup, backup, sync
+   - **Custom** — any repeatable task
+
+**Exit:** Chore understood, steps clear.
+
+### Phase 2: Design Chore Structure
+
+Plan the chore:
+
+1. **Name** — kebab-case, descriptive (e.g., `push-github-main`, `publish-npm`)
+2. **Steps** — ordered list of commands/actions
+3. **Pre-conditions** — what must be true before running
+4. **Post-conditions** — what should be true after success
+5. **Failure handling** — what to do if steps fail
+6. **Interactive points** — where user input may be needed
+
+**Exit:** Structure designed.
+
+### Phase 3: Write Chore File
+
+Create `.unipi/docs/chore/<chore-name>.md`:
+
+```markdown
+---
+name: {chore-name}
+type: chore
+description: {One-line description}
+created: YYYY-MM-DD
+---
+
+# {Chore Name}
+
+{Description of what this chore does and when to use it}
+
+## Pre-conditions
+
+Before running this chore, ensure:
+- [ ] {Pre-condition 1}
+- [ ] {Pre-condition 2}
+
+## Steps
+
+### Step 1: {Step Name}
+{What to do}
+
+```bash
+{command}
+```
+
+Expected: {what should happen}
+
+### Step 2: {Step Name}
+{What to do}
+
+```bash
+{command}
+```
+
+Expected: {what should happen}
+
+### Step N: Verify
+{How to verify success}
+
+```bash
+{verification command}
+```
+
+Expected: {success indicator}
+
+## Failure Handling
+
+If any step fails:
+1. {What to check}
+2. {How to recover}
+3. {When to abort}
+
+## Post-conditions
+
+After successful completion:
+- [ ] {Post-condition 1}
+- [ ] {Post-condition 2}
+
+## Notes
+{Any additional context, gotchas, or tips}
+```
+
+### Phase 4: Self-Review
+
+Before presenting:
+1. Are all steps clear and executable?
+2. Are commands correct and tested?
+3. Is failure handling comprehensive?
+4. Would someone else be able to run this?
+
+### Phase 5: Present & Handoff
+
+Present to user:
+
+> "Chore created at `.unipi/docs/chore/<chore-name>.md`"
+>
+> **Steps:** {count} steps
+> **Type:** {deploy/publish/git/etc.}
+
+Then suggest:
+
+```
+/unipi:chore-execute chore:<chore-name>
+```
+
+Or if more chores needed:
+> "Need to create more chores?"
+
+---
+
+## Chore Naming Convention
+
+Use kebab-case with action-verb prefix:
+
+| Pattern | Example |
+|---------|---------|
+| `push-{target}` | `push-github-main`, `push-github-develop` |
+| `publish-{registry}` | `publish-npm`, `publish-docker` |
+| `deploy-{env}` | `deploy-staging`, `deploy-production` |
+| `run-{suite}` | `run-unit-tests`, `run-e2e-tests` |
+| `sync-{service}` | `sync-translations`, `sync-config` |
+| `backup-{target}` | `backup-database`, `backup-files` |
+| `release-{type}` | `release-patch`, `release-minor` |
+
+---
+
+## Examples
+
+### Push to GitHub Main
+
+```
+/unipi:chore-create push current branch to github main
+```
+
+Creates `.unipi/docs/chore/push-github-main.md`:
+```markdown
+---
+name: push-github-main
+type: chore
+description: Push current branch changes to GitHub main
+created: 2026-04-28
+---
+
+# Push to GitHub Main
+
+Push committed changes from current branch to GitHub main branch.
+
+## Pre-conditions
+- [ ] All changes committed
+- [ ] On correct branch
+- [ ] Tests passing
+
+## Steps
+
+### Step 1: Verify clean working tree
+```bash
+git status
+```
+Expected: "nothing to commit, working tree clean"
+
+### Step 2: Push to remote
+```bash
+git push origin main
+```
+Expected: Success with no errors
+
+### Step 3: Verify push
+```bash
+git log --oneline -1
+```
+Expected: Latest commit matches remote
+
+## Failure Handling
+If push rejected:
+1. Pull latest: `git pull origin main`
+2. Resolve conflicts if any
+3. Retry push
+
+## Post-conditions
+- [ ] Remote main is up to date
+```
+
+### Publish to NPM
+
+```
+/unipi:chore-create publish package to npm registry
+```
+
+Creates `.unipi/docs/chore/publish-npm.md`:
+```markdown
+---
+name: publish-npm
+type: chore
+description: Publish package to npm registry
+created: 2026-04-28
+---
+
+# Publish to NPM
+
+Publish the current package version to npm registry.
+
+## Pre-conditions
+- [ ] Logged in to npm (`npm whoami`)
+- [ ] Version bumped in package.json
+- [ ] All changes committed
+- [ ] Tests passing
+
+## Steps
+
+### Step 1: Verify npm login
+```bash
+npm whoami
+```
+Expected: Your npm username
+
+### Step 2: Run tests
+```bash
+npm test
+```
+Expected: All tests passing
+
+### Step 3: Build package
+```bash
+npm run build
+```
+Expected: Build succeeds
+
+### Step 4: Publish
+```bash
+npm publish
+```
+Expected: Package published successfully
+
+### Step 5: Verify publication
+```bash
+npm view {package-name} version
+```
+Expected: Matches package.json version
+
+## Failure Handling
+If publish fails:
+1. Check npm login: `npm whoami`
+2. Check version: must be higher than current
+3. Check package name conflicts
+
+## Post-conditions
+- [ ] Package available on npm
+- [ ] Version matches package.json
+```
+
+---
+
+## Notes
+
+- Chores are reusable — create once, execute many times
+- Keep steps clear and executable by anyone
+- Include verification steps for confidence
+- Document failure scenarios for resilience
+- Chores are stored in `.unipi/docs/chore/` for discoverability

package/skills/chore-execute/SKILL.md

@@ -0,0 +1,312 @@
+---
+name: chore-execute
+description: "Execute a saved chore — run deploy, publish, push, or any repeatable task from docs/chore/."
+---
+
+# Executing Chores
+
+Run saved chore definitions. Autocomplete available for chore file selection.
+
+## Boundaries
+
+**This skill MAY:** read chore file, run commands, ask user for confirmation, report results.
+**This skill MAY NOT:** create new chores, edit code (unless chore requires it).
+
+## Command Format
+
+```
+/unipi:chore-execute chore:<path>(optional) <string(greedy)>(optional)
+```
+
+- `chore:<path>` — chore file to execute (autocomplete available)
+- `string(greedy)` — optional context or overrides (e.g., "skip tests", "dry run")
+- If no chore provided → agent lists available chores and asks
+
+## Input Path
+
+```
+.unipi/docs/chore/<chore-name>.md
+```
+
+---
+
+## Process
+
+### Phase 1: Load Chore
+
+**If `chore:` arg provided:**
+1. Read the chore file from `.unipi/docs/chore/`
+2. Understand: steps, pre-conditions, failure handling
+
+**If no chore provided:**
+1. List available chore files in `.unipi/docs/chore/`
+2. Present to user for selection (autocomplete-style)
+
+```
+Available chores:
+┌─────────────────────────────┬─────────────────────────────────────┐
+│ Chore                       │ Description                         │
+├─────────────────────────────┼─────────────────────────────────────┤
+│ push-github-main.md         │ Push current branch to GitHub main  │
+│ publish-npm.md              │ Publish package to npm registry     │
+│ deploy-staging.md           │ Deploy to staging environment       │
+│ run-full-tests.md           │ Run complete test suite             │
+└─────────────────────────────┴─────────────────────────────────────┘
+```
+
+**Exit:** Chore loaded. Steps understood.
+
+### Phase 2: Pre-condition Check
+
+Before executing, verify pre-conditions:
+
+1. Read pre-conditions from chore file
+2. For each pre-condition:
+   - Run verification command if provided
+   - Ask user to confirm if manual check
+   - Report status
+
+```
+Pre-conditions:
+✓ All changes committed — verified
+✓ On correct branch — verified (main)
+? Tests passing — should I run tests first?
+```
+
+**If pre-conditions fail:**
+> "Pre-condition not met: {description}. Fix this before continuing?"
+- If yes → help fix or wait for user
+- If no → abort chore
+
+**If `string(greedy)` contains overrides:**
+- "skip tests" → skip test steps
+- "dry run" → show commands without executing
+- "force" → skip pre-condition checks (with warning)
+
+**Exit:** Pre-conditions verified (or overridden).
+
+### Phase 3: Execute Steps
+
+For each step in the chore:
+
+1. **Display step:**
+   ```
+   Step 2/5: Push to remote
+   > git push origin main
+   ```
+
+2. **Confirm execution** (for destructive commands):
+   > "Execute this step?"
+
+3. **Run command:**
+   ```bash
+   {command}
+   ```
+
+4. **Check result:**
+   - If success → proceed to next step
+   - If failure → go to Phase 4 (Failure Handling)
+
+5. **Report progress:**
+   ```
+   ✓ Step 1/5: Verify clean working tree
+   ✓ Step 2/5: Push to remote
+   ○ Step 3/5: Verify push (running...)
+   ```
+
+**Exit:** All steps completed.
+
+### Phase 4: Failure Handling (if needed)
+
+If a step fails:
+
+1. **Report failure:**
+   ```
+   ✗ Step 2/5: Push to remote — FAILED
+   Error: rejected (non-fast-forward)
+   ```
+
+2. **Check chore's failure handling section:**
+   - Follow recovery steps
+   - Run diagnostic commands
+   - Ask user for decision
+
+3. **Options:**
+   - **Retry** — try the step again
+   - **Skip** — skip this step (if non-critical)
+   - **Abort** — stop chore execution
+   - **Manual** — user handles this step
+
+4. **If recovery succeeds:**
+   > "Recovered from failure. Continuing..."
+   → Resume execution
+
+5. **If recovery fails:**
+   > "Cannot recover. Chore aborted at step {N}."
+   → Report what was completed and what remains
+
+### Phase 5: Verify Completion
+
+After all steps complete:
+
+1. Run post-condition checks
+2. Run verification commands from chore
+3. Report success:
+
+```
+Chore Complete: {chore-name}
+
+✓ Step 1: {name}
+✓ Step 2: {name}
+✓ Step 3: {name}
+✓ Step 4: {name}
+✓ Step 5: {name}
+
+Post-conditions:
+✓ {Post-condition 1} — verified
+✓ {Post-condition 2} — verified
+```
+
+### Phase 6: Report
+
+> "Chore `{chore-name}` completed successfully."
+
+If there were issues:
+> "Chore completed with notes: {notes}"
+
+---
+
+## Autocomplete Behavior
+
+When user types `/unipi:chore-execute chore:`, autocomplete shows:
+
+```
+Available chores:
+┌─────────────────────────────┬────────────┬─────────────────────────────────────┐
+│ File                        │ Type       │ Description                         │
+├─────────────────────────────┼────────────┼─────────────────────────────────────┤
+│ push-github-main.md         │ git        │ Push current branch to GitHub main  │
+│ publish-npm.md              │ publish    │ Publish package to npm registry     │
+│ deploy-staging.md           │ deploy     │ Deploy to staging environment       │
+└─────────────────────────────┴────────────┴─────────────────────────────────────┘
+```
+
+User selects one, or types path manually.
+
+---
+
+## Context Overrides
+
+The `string(greedy)` parameter can override chore behavior:
+
+| Override | Effect |
+|----------|--------|
+| `skip tests` | Skip test/verification steps |
+| `dry run` | Show commands without executing |
+| `force` | Skip pre-condition checks |
+| `verbose` | Show detailed output |
+| `step 3` | Start from step 3 |
+
+Example:
+```
+/unipi:chore-execute chore:publish-npm skip tests
+```
+
+---
+
+## Examples
+
+### Execute Push to GitHub
+
+```
+/unipi:chore-execute chore:push-github-main
+```
+
+Output:
+```
+Loading chore: push-github-main
+Description: Push current branch changes to GitHub main
+
+Pre-conditions:
+✓ All changes committed — verified (3 files committed)
+✓ On correct branch — verified (main)
+
+Executing steps:
+
+Step 1/3: Verify clean working tree
+> git status
+✓ Working tree clean
+
+Step 2/3: Push to remote
+> git push origin main
+✓ Pushed to origin/main
+
+Step 3/3: Verify push
+> git log --oneline -1
+✓ Remote matches local
+
+Post-conditions:
+✓ Remote main is up to date
+
+Chore push-github-main completed successfully.
+```
+
+### Execute Publish to NPM (with override)
+
+```
+/unipi:chore-execute chore:publish-npm dry run
+```
+
+Output:
+```
+Loading chore: publish-npm
+Description: Publish package to npm registry
+Mode: DRY RUN (commands shown but not executed)
+
+Steps that would run:
+1. npm whoami
+2. npm test
+3. npm run build
+4. npm publish
+5. npm view @pi-unipi/workflow version
+
+Dry run complete. No commands executed.
+```
+
+---
+
+## Error Recovery
+
+When a step fails, the agent should:
+
+1. **Diagnose** — understand why it failed
+2. **Suggest** — propose recovery steps
+3. **Execute** — try recovery if user approves
+4. **Report** — explain what happened
+
+Example:
+```
+Step 2/5: Push to remote
+> git push origin main
+✗ FAILED: rejected (non-fast-forward)
+
+Diagnosis: Remote has commits not in local branch
+
+Recovery options:
+1. Pull and merge: git pull origin main
+2. Force push: git push --force origin main (dangerous!)
+3. Abort chore
+
+Which option?
+```
+
+---
+
+## Notes
+
+- Chores are reusable — same chore can be run many times
+- Autocomplete makes it easy to find the right chore
+- Pre-condition checks prevent common failures
+- Failure handling provides recovery paths
+- Context overrides allow flexibility without editing chore files
+- Chores stored in `.unipi/docs/chore/` for discoverability