diff --git a/.actrc b/.actrc deleted file mode 100644 index 5c08277..0000000 --- a/.actrc +++ /dev/null @@ -1 +0,0 @@ --P ubuntu-latest=catthehacker/ubuntu:act-latest diff --git a/.changeset/README.md b/.changeset/README.md index aded9a4..65273ab 100644 --- a/.changeset/README.md +++ b/.changeset/README.md @@ -24,7 +24,7 @@ Use this structure for your changeset content: ```markdown --- -"@thiagodiogo/pastelsdd": patch +"@thiagodiogo/pscode": patch --- ### New Features diff --git a/.changeset/guided-sdd-installer.md b/.changeset/guided-sdd-installer.md new file mode 100644 index 0000000..7937270 --- /dev/null +++ b/.changeset/guided-sdd-installer.md @@ -0,0 +1,124 @@ +--- +"@thiagodiogo/pscode": major +--- + +Reframe PSCode as a lightweight guided-SDD installer. + +PSCode is no longer a spec-driven-development framework with a workflow engine, +artifact DAG, schemas and deep validation. It is now a small installer that lays +down the rails — slash commands, skills, instructions and a minimal `pscode/` +structure — so a coding agent runs a short, human-validated flow. + +- New CLI: `init`, `update`, `doctor`, `clean`, `status`. +- Installs 6 slash commands (`/ps:draft`, `/ps:refine`, `/ps:dev`, + `/ps:complete`, `/ps:cancel`, `/ps:board-setup`) and 9 skills + (`pscode-guided-sdd`, `pscode-grill-me`, `pscode-refine`, `pscode-mini-spec`, + `pscode-task-runner`, `pscode-dev`, `pscode-complete`, `pscode-github-sync`, + `pscode-board-setup`) for Claude Code, Codex, Cursor and Gemini. The guided + flow mirrors the GitHub Project board, moving the card at each step: + `/ps:draft` (Backlog) → `/ps:refine ` (In Refinement → Ready to Dev) → + `/ps:dev ` (In Development → In Code Review → In Test → Ready to Deploy) + → `/ps:complete ` (Done). `/ps:cancel ` sends a card to Cancelled. + Every command accepts the card number for direct reference. +- `/ps:refine` claims the card (assigns the user, moves it to In Refinement), + analyzes the code, runs Grill Me, and turns the draft into a refined, + issue-ready document in one standard format (lean summary, technical detail, + in/out of scope, subtask breakdown) written to `pscode/changes//refine.md`. + When `pscode/github.yaml` exists it reads the open Issue description + comments + as input and, on approval, turns each `## Subtasks` item into a native + **sub-issue** of the card (so the board shows the breakdown + a progress bar), + updates the Issue body from `refine.md` (dropping the now-redundant checklist), + and moves the card to **Ready to Dev**. `/ps:dev` closes each sub-issue as its + subtask is ticked. +- `/ps:dev` opens a draft PR linked to the Issue (`Closes #`), moves the card to + In Development and assigns the user, implements the `refine.md` subtasks one at + a time, then — once the project builds and its tests pass — walks the card + through In Code Review (PR marked Ready for Review) → In Test → Ready to + Deploy. Merging the PR stays a human/CI decision. +- `/ps:complete` writes a short openspec-style delta spec, archives the change to + `pscode/changes/archive/-/`, and moves the card to Done + (closing the Issue). `/ps:cancel` archives with a reason and moves the card to + Cancelled. +- Adds `pscode/config.yaml` (short-document limits + one-task-at-a-time and + approval guardrails) and short change templates. +- Writes the managed instruction block into the file each selected agent reads: + Claude Code → `CLAUDE.md`, the others → `AGENTS.md` (both when mixed). +- `init` is an interactive wizard by default (language → agents), with `--yes` + and explicit flags as the non-interactive bypass. The agent picker offers only + Claude Code (marked recommended) and Codex; Cursor and Gemini stay reachable + via `--agent` and detection. +- `pscode init` can enable Claude Code's `bypassPermissions` mode: when Claude + Code is selected, the wizard asks whether to write + `permissions.defaultMode: bypassPermissions` into `.claude/settings.json` + (merging into existing settings). Defaults to yes; control it with + `--bypass-permissions` / `--no-bypass-permissions`. Never written when Claude + Code is not selected. Its yes/no prompt resolves on the first keypress. +- When `init` finishes it can open the selected agent's CLI (`claude`, `codex` + or `gemini`) — Claude Code preferred when more than one is selected — handing + off the terminal. Defaults to yes and is honored in `--yes` runs; control it + with `--open` / `--no-open`. The agent is only launched when a real terminal + is present; in CI or piped runs PSCode prints how to start it instead of + blocking. Cursor has no unambiguous CLI, so it is never auto-opened. +- `update` now wipes the `commands/ps/` folder and every `skills/pscode-*` folder + before rewriting, so commands or skills removed/renamed in a new version don't + linger. +- **Environment verification concentrated in `init`** (`core/preflight.ts`): + `init` and `doctor` run a non-blocking check — Git installed, inside a repo, + GitHub remote, GitHub CLI installed and authenticated, Node version, the + selected agent CLI — and scan the project's MCP config files (`.mcp.json`, + `.cursor/mcp.json`, `.vscode/mcp.json`, `.claude/settings*.json`) for declared + MCP servers. A failing check prints how to fix it and `init` carries on. (A CLI + can only see whether an MCP is *declared*, not *connected* — that stays the + agent's job.) +- **GitHub Projects + Issues setup** (`core/github.ts`, `commands/init-github.ts`): + one wizard question — use an existing Project, create a new one, or skip. For + an existing Project it lists the account's Projects to pick from (plus an + "Other — paste a link" fallback); when creating, it prompts for the Project + name (defaulting to the project folder name). It discovers the GraphQL ids via + `gh` and writes `pscode/github.yaml` (repo, + project node id, Status field id, stage→option-id map). Non-interactive via + `--project `; skipped by default when non-interactive. Every `gh` call is + non-blocking. New flags: `--github` / `--no-github`, `--project `. + A new `github.enabled` flag in `config.yaml` records it (and `update` preserves + it). +- **Per-step board sync** (`pscode-github-sync` skill + sections in the command + bodies): when `pscode/github.yaml` exists the agent keeps the Issue, board, + assignee and PR in sync across the nine columns — `/ps:draft` creates the + Issue, adds it to the Project, sets **Backlog** and stores the number in + `pscode/changes//.issue`; `/ps:refine` → **In Refinement** (assigns the + user) then **Ready to Dev**; `/ps:dev` opens a draft PR and goes **In + Development** → **In Code Review** → **In Test** → **Ready to Deploy**; + `/ps:complete` → **Done** (closes the Issue); `/ps:cancel` → **Cancelled**. The + change↔issue link resolves deterministically (`links` → `.issue` → + `-NN`, via `resolveIssueNumber`), and every command also accepts + the card number directly. `github.yaml` now also stores the Project `owner` so + `gh project …` calls work for org-owned Projects. "Non-blocking" means tolerate + failure, **not** skip the work: the agent always *attempts* every action a step + prescribes — the status move (two `gh` calls: `item-list` then `item-edit`) is + the core action and is never skipped just because the cheaper `assign` already + ran — and confirms the move landed; only a `gh`/auth/network failure makes it + report and carry on. +- **Board setup** (`/ps:board-setup` + `pscode-board-setup` skill): a fresh + GitHub Project is a plain Table with the default Status options. This command + drives the GitHub UI through the **Chrome MCP** to create the kanban columns + (Backlog, In Refinement, Ready to Dev, In Development, In Code Review, In Test, + Ready to Deploy, Done, Cancelled) and switch the view to a Status-grouped + Board, then re-discovers the option ids via `gh` and rewrites the `statuses` + map in `pscode/github.yaml`. Whenever the board is set up (existing or new + Project), `init` hands off straight into `/ps:board-setup` if it opens Claude + Code, otherwise it prints a hint to run it. `github.yaml` now also stores the + Project `ownerType` so the board URL can be built. The flow's nine stages map + one-to-one onto the columns (`backlog`, `proposed`/In Refinement, + `ready_to_dev`, `in_progress`/In Development, `review`/In Code Review, + `in_test`, `ready_to_deploy`, `done`, `cancelled`), all written into the + `statuses` map by `/ps:board-setup`. +- **Requirements manifest** (`pscode/requirements.yaml`): `init` writes what each + active integration needs and what it verified (preflight results + declared + MCPs), for the agent to consume instead of re-probing the environment. +- The "open the agent now?" prompt runs **last** — after every other question + (language, agents, bypassPermissions, GitHub) and after the install summary. +- Removes the workflow engine, schemas, artifact graph, validation, workspaces, + context store/initiatives, telemetry, completions, the local board and related + commands. + +BREAKING CHANGE: the previous commands, schemas and APIs have been removed. diff --git a/.claude/commands/ps/apply.md b/.claude/commands/ps/apply.md deleted file mode 100644 index 7653598..0000000 --- a/.claude/commands/ps/apply.md +++ /dev/null @@ -1,431 +0,0 @@ ---- -name: "PS: Apply" -description: Implement tasks from a Pscode change -category: Workflow -tags: [workflow, apply, implementation] ---- - -## Asking the user - -When this workflow needs a decision or confirmation from the user, prefer the -`AskUserQuestion` tool over a free-text question: - -- Use `AskUserQuestion` for any decision or confirmation (e.g. "Which approach?", - "Can I open the PR?", "Move the card to Ready to Dev?"). Present 2–4 concrete, - mutually exclusive options. -- Always keep the embedded free-text answer ("Other") available — never remove - it. The user can always type a custom response. -- Fall back to a plain free-text question only when there are no reasonable - options to offer, or when `AskUserQuestion` is unavailable. -- Do NOT use `AskUserQuestion` for progress updates or status messages — only - for genuine questions that need the user's input. - -Implement tasks from a Pscode change. - -**Input**: Optionally specify a change name (e.g., `/ps:apply add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes. - -**Steps** - -1. **Select the change** - - If a name is provided, use it. Otherwise: - - Infer from conversation context if the user mentioned a change - - Auto-select if only one active change exists - - If ambiguous, run `pscode list --json` to get available changes and use the **AskUserQuestion tool** to let the user select - - Always announce: "Using change: " and how to override (e.g., `/ps:apply `). - -2. **Tracker Integration — signal development start (optional)** - - This is the FIRST action after selecting the change — signal immediately that development has started. - - **Detect active tracker** using the **Read tool** (NOT shell commands): - 1. Read `pscode/trello.yaml`. If found and `configured: true` → **tracker = trello**. - 2. Else read `pscode/github.yaml`. If found → **tracker = github**. - 3. Else → no tracker, skip to Step 3. - - --- - - **If tracker = trello:** - - Parse and extract `boardId`, `lists.refining`, `lists.ready`, `lists.developing`, and `lists.testing`. - - Search for the change's card across configured lists in priority order: - `refining` → `ready` → `backlog` (whichever are configured): - ```tool - mcp__claude_ai_Trello_Custom__get_cards { list_id: "" } - ``` - Look for a card matching the change name (case-insensitive, partial match is sufficient). - - **If `lists.developing` is configured:** - - **Card found:** move it to `lists.developing`. - - **No card found:** create one directly in `lists.developing` with name and desc in Portuguese. - - **If `lists.developing` is NOT configured and `lists.ready` is configured:** - - Move/create in `lists.ready`. - - In all cases, assign the current user: - ```tool - mcp__claude_ai_Trello_Custom__get_me - mcp__claude_ai_Trello_Custom__add_card_member { card_id: "", member_id: "" } - ``` - Save `cardId` for the completion step. - - If any Trello call fails, continue — Trello is auxiliary, never blocking. - - --- - - **If tracker = github:** - - Parse and extract: `repo`, `project`, `projectNodeId`, `statusFieldId`, `statuses.in_progress`, `gh` (default: `gh`), `issuePattern` (default: `issue`). - Extract `owner` from `repo` (component before `/`). - - **Extract issue number from change name:** - - First check `links:` map in `pscode/github.yaml` for an exact match on the change name. - - Then match pattern `-NN` (e.g. `issue-42`) → N as integer. - - No match → `issueNumber = null`. - - **Find the GitHub Projects item** (if `issueNumber` is not null): - ```bash - "" project item-list --owner "" --format json - ``` - Parse to find item where `content.number == issueNumber`. Save `id` as `ghItemId`. - If not found → `ghItemId = null`, log and continue. - - **Update status to `in_progress`** (if `ghItemId` is not null and `statuses.in_progress` is configured): - ```bash - "" project item-edit --id --field-id --project-id --single-select-option-id - ``` - - Save `ghItemId`, `issueNumber`, and `ghConfig` for later steps. - - If any `gh` call fails, continue — GitHub Projects is auxiliary, never blocking. - -3. **Check status to understand the schema** - ```bash - pscode status --change "" --json - ``` - Parse the JSON to understand: - - `schemaName`: The workflow being used (e.g., "spec-driven") - - `planningHome`, `changeRoot`, and `actionContext`: planning scope and edit constraints - - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others) - -4. **Get apply instructions** - - ```bash - pscode instructions apply --change "" --json - ``` - - This returns: - - `contextFiles`: artifact ID -> array of concrete file paths (varies by schema) - - Progress (total, complete, remaining) - - Task list with status - - Dynamic instruction based on current state - - **Handle states:** - - If `state: "blocked"` (missing artifacts): show message, suggest using `/ps:continue` - - If `state: "all_done"`: congratulate, suggest archive - - Otherwise: proceed to implementation - - **Workspace guard:** If status JSON reports `actionContext.mode: "workspace-planning"` and `allowedEditRoots` is empty, explain that full workspace apply is not supported in this slice. Treat linked repos and folders as read-only context, ask the user to select an affected area, and STOP before editing files. - -5. **Read context files and PR config** - - Read every file path listed under `contextFiles` from the apply instructions output. - - Additionally, use the **Read tool** to read `pscode/config.yaml` from the current working directory. - - **If `pscode/config.yaml` exists and `pr.enabled: true`:** - - Before starting any implementation, inform the user of the PR workflow requirements: - - > 🔀 **Workflow de PR ativo** — este projeto requer branches dedicadas e Pull Requests. - > - Branch: crie uma branch com o padrão `` antes de codificar - > - Título do PR: `` - > - Descrição do PR: use o template definido em `pr.description.template` - > - Ao abrir o PR: `<"comente o link do PR nesta task" se pr.comments.linkInTask: true, senão omita>` - - Template variables available: `{change-name}` = current change name, `{type}` = feat/fix/chore, `{ticket}` = ticket ID if available. - - **Detect whether a PR already exists for this change** (it may have been opened in `/ps:propose`). Resolve the branch name from `pr.branch.pattern`, then check the current branch and its PR: - ```bash - git checkout # if it already exists; otherwise it will be created below - gh pr view --json state,url - ``` - - - **If a PR already exists** (the `gh pr view` returns an open PR): do NOT open another — just continue working on the existing PR. Save its URL as `prUrl`. - - - **If NO PR exists:** open one in **DRAFT automatically, without asking the user**: - 1. Create the branch with the configured `pr.branch.pattern` if it does not exist yet (`git checkout -b `) — the agent MUST be on this branch before making any code changes. - 2. Commit any pending planning artifacts: `git add -A && git commit -m "chore(): planning artifacts"` (skip if nothing to commit). - 3. Push and set upstream: `git push -u origin `. - 4. Open the PR in DRAFT, deriving the title from `pr.title.template` and the body from `pr.description.template`. - - **Referência da task no corpo (tracker):** - - **Trello:** if `pr.taskLinkInDescription` is not `false` and a `cardId` was saved in Step 2, prefix the body with `Task: `. Skip gracefully when no `cardId`. - - **GitHub Projects:** if `pr.taskLinkInDescription` is not `false` and `issueNumber` was saved in Step 2, prefix the body with `Task: https://github.com//issues/`. Skip gracefully when no `issueNumber`. - - Never block on tracker reference — always open the PR and edit the body later if needed. - - `gh pr create --draft --title "" --body ""`. - 5. Capture the PR URL as `prUrl`. - - **Comentário do link no tracker:** after opening a PR (or detecting an existing one just opened), if `pr.comments.linkInTask: true`: - - **Trello:** if a `cardId` was saved in Step 2, comment the PR link on the card: - ```tool - mcp__claude_ai_Trello_Custom__add_comment - card_id: "" - text: | - 🔀 Pull Request (DRAFT): - ``` - - **GitHub Projects:** if `issueNumber` is not null: - ```bash - "" issue comment --repo --body "🔀 Pull Request (DRAFT): " - ``` - - **Tratamento de falha (não-bloqueante):** if `gh` or `git` fails — `gh` not installed, not authenticated, or no GitHub remote — **do NOT block**: state what failed and how to fix it (e.g., `gh auth login`), ask whether the user wants the agent to resolve it in parallel, and **continue the implementation regardless**. The branch and local commits are preserved. - - **If `pscode/config.yaml` does not exist, or `pr.enabled: false`, or file not found:** continue normally without any PR instructions — no branch, no PR. - -6. **Show current progress** - - Display: - - Schema being used - - Progress: "N/M tasks complete" - - Remaining tasks overview - - Dynamic instruction from CLI - -7. **Implement tasks (loop until done or blocked)** - - For each pending task: - - Show which task is being worked on - - Make the code changes required - - Keep changes minimal and focused - - Mark task complete in the tasks file: `- [ ]` → `- [x]` - - Continue to next task - - **Pause if:** - - Task is unclear → ask for clarification - - Implementation reveals a design issue → suggest updating artifacts - - Error or blocker encountered → report and wait for guidance - - User interrupts - -8. **On completion: populate the PR, then move card to "Em Teste" (optional)** - - When all tasks are complete (`state: "all_done"`): - - **8.0 — Popular o PR ativo e promovê-lo para "ready for review"** - - Only when `pscode/config.yaml` exists, `pr.enabled: true`, and an active PR was opened/detected for the branch (a saved `prUrl`). Otherwise skip this sub-step silently. - - a. Build a **rich, fixed PR body** (NOT the `pr.description.template`) from the change artifacts, in this order: - - **Resumo / Objetivo** — derived from `proposal.md` (*Why* / *What Changes*), 1-2 sentences. - - **Decisões técnicas** — the key decisions from `design.md`, as an enxuta list. - - **Tasks concluídas** — the completed tasks from `tasks.md`. - - **Escopo** — what is and isn't included, when available in the artifacts. - - **Referências** — the Trello card link (when a `cardId` was saved) and the `pscode/changes//` path. - - Keep each section concise — the goal is a self-sufficient PR, not a dump of the artifacts. Apply it via: - ```bash - gh pr edit --body "" - ``` - - b. Promote the PR from draft to "ready for review": - ```bash - gh pr ready - ``` - If the PR is already in "ready", `gh pr ready` is a no-op — do not treat that as an error. - - **Tratamento de falha (não-bloqueante):** if any `gh` call fails — `gh` not installed, not authenticated, no GitHub remote, or no PR — state what failed and how to fix it (e.g., `gh auth login`), and **continue the flow regardless**. Never block on PR population/promotion. - - **8.1 — Update tracker to testing/in_review stage** - - **If tracker = trello** and `cardId` was saved: - - a. If `lists.testing` is configured, move the card there: - ```tool - mcp__claude_ai_Trello_Custom__update_card { card_id: "", list_id: "" } - ``` - - b. Add a comment in Portuguese: - ```tool - mcp__claude_ai_Trello_Custom__add_comment - card_id: "" - text: | - Implementacao concluida via /ps:apply - - Change: - Tasks: / concluidas - - Aguardando validacao antes de mover para Ready to Deploy. - ``` - - If any Trello call fails, continue — Trello is auxiliary, never blocking. - - **If tracker = github** and `ghItemId` was saved: - - a. Update status to `in_review` (if `statuses.in_review` is configured): - ```bash - "" project item-edit --id --field-id --project-id --single-select-option-id - ``` - - b. Add a comment to the GitHub Issue (if `issueNumber` is not null): - ```bash - "" issue comment --repo --body "Implementacao concluida via /ps:apply - - Change: - Tasks: / concluidas - - Aguardando validacao antes de arquivar." - ``` - - If any `gh` call fails, continue — GitHub Projects is auxiliary, never blocking. - -9. **Fase de Testes — validar implementação** - - After completing all tasks (and moving the card to "Em Teste" if Trello is configured), - use the **AskUserQuestion tool** to ask how the user wants to proceed with validation: - - - **"Vou testar eu mesmo"** — user will test independently; wait for them to report back - - **"Quero que você teste"** — Claude should invoke the `verify` skill to validate the implementation - - **"Já testei, está funcionando"** — user already confirmed; proceed to move card to "Ready to Deploy" - - **If user chooses "Vou testar eu mesmo":** - - Tell them to test and come back when ready (e.g., saying "está funcionando" or "encontrei um problema") - - Wait — do NOT proceed until the user responds - - **If user chooses to have Claude test:** - - Use the **Skill tool** to invoke the `verify` skill, which runs the app and observes the change - - Report the findings clearly to the user - - Ask: "A implementação está funcionando como esperado?" (Sim / Não, encontrei um problema) - - **When the user confirms it's working** (any path above): - - **Reatualizar o corpo do PR (não-bloqueante):** if `pscode/config.yaml` has `pr.enabled: true` and an active PR exists (`prUrl`), update the PR body again to incorporate the validation result — append a **Validação** section recording that the implementation was validated, who tested it (the user, or Claude via the `verify` skill), and the approved status. Apply via `gh pr edit --body ""`, preserving the rich body from step 8. If `gh` fails, report it and continue — never block. - - If Trello is configured, `cardId` was saved, and `lists.deploy` is configured: - a. Move the card to "Ready to Deploy": - ```tool - mcp__claude_ai_Trello_Custom__update_card { card_id: "", list_id: "" } - ``` - b. Add a comment in Portuguese: - **IMPORTANT**: Replace `` below with the actual card title — the command **must always** include the quoted title argument, never post `/ps:complete` by itself. - ```tool - mcp__claude_ai_Trello_Custom__add_comment - card_id: "" - text: | - Implementacao validada e aprovada para deploy. - - Testado por: - Status: Funcionando - - ## Próximo passo - - Para finalizar e arquivar a change, rode: - - ``` - /ps:complete "" - ``` - ``` - - If any Trello call fails, continue — Trello is auxiliary, never blocking. - - **If user reports a problem:** - - Acknowledge the issue and ask for details - - Resume implementation to fix the problem (loop back to step 7) - - Do NOT move the card to "Ready to Deploy" until the user confirms it's working - -10. **On completion or pause, show status** - - Display: - - Tasks completed this session - - Overall progress: "N/M tasks complete" - - If all done and approved: mention Trello stage (Em Teste or Ready to Deploy) and suggest `/ps:complete` - - If paused: explain why and wait for guidance - -**Output During Implementation** - -``` -## Implementing: (schema: ) - -Working on task 3/7: -[...implementation happening...] -✓ Task complete - -Working on task 4/7: -[...implementation happening...] -✓ Task complete -``` - -**Output On Completion (aguardando testes)** - -``` -## Implementation Complete - -**Change:** -**Schema:** -**Progress:** 7/7 tasks complete ✓ -**PR:** Populated and promoted to ✅ ready for review ← only shown if pr.enabled and an active PR exists -**Tracker:** ← only shown if a tracker is configured - -### Completed This Session -- [x] Task 1 -- [x] Task 2 -... - -All tasks complete! How would you like to validate the implementation? -``` - -**Output After Validation Approved** - -``` -## Validation Approved ✅ - -**Change:** -**PR:** Body updated with validation result ← only shown if pr.enabled and an active PR exists -**Tracker:** ← only shown if a tracker is configured - -Ready to archive with `/ps:complete`. -``` - -**Output On Pause (Issue Encountered)** - -``` -## Implementation Paused - -**Change:** -**Schema:** -**Progress:** 4/7 tasks complete - -### Issue Encountered - - -**Options:** -1.