@tacuchi/agent-workflow-cli 4.0.0

package/skills/agent-workflow/references/orchestration.md

@@ -0,0 +1,86 @@
+# Orchestration
+
+Decision-support commands the lifecycle skill uses during planning and execution: when to plan, when the topic changed, which specialty to compose, what phase you are in, what the workspace stack looks like.
+
+## auto-plan-decide
+
+Decide whether an OBJETIVO needs full planning, lite planning, or skip-to-execution. Returns a recommendation plus an estimated effort in hours.
+
+```bash
+agent-workflow auto-plan-decide --objetivo "Bug: login redirect loop"
+agent-workflow auto-plan-decide --objetivo-file .qtc/sessions/sessionNNN-.../OBJETIVO.md
+```
+
+Output:
+
+```json
+{ "scope": "lite", "rationale": "...", "eta_hours": 2.0 }
+```
+
+`scope` is one of `skip` | `lite` | `full`.
+
+## topic-change-check
+
+Detect whether a fresh user request diverges from the active session's OBJETIVO. Used to suggest opening a new session instead of polluting the current one.
+
+```bash
+agent-workflow topic-change-check \
+  --objetivo-file .qtc/sessions/sessionNNN/OBJETIVO.md \
+  --request "Quiero refactorizar el módulo de pagos"
+```
+
+Both `--objetivo` (or `--objetivo-file`) and `--request` are required.
+
+## specialty-choose
+
+Recommend specialty skills (and whether to invoke them explicitly) for a given phase + OBJETIVO. The host plugin can register specialty workflows; this command surfaces the matches.
+
+```bash
+agent-workflow specialty-choose --phase execution --objetivo "Construir CRUD de productos"
+agent-workflow specialty-choose --phase planning --objetivo-file path/to/OBJETIVO.md
+```
+
+`--phase` is required. `--objetivo` (or `--objetivo-file`) is optional but recommended.
+
+## phase-detect
+
+Suggest the current session phase from the artifacts on disk (no mutation). Inspects which of `OBJETIVO.md`, `TASKS.md`, `DECISIONES.md`, `CHECKPOINT.md`, etc. are present and how complete they are.
+
+```bash
+agent-workflow phase-detect --code session035
+```
+
+## phase-next
+
+Advance the session phase to the next slot in the lifecycle (planning → execution → validation → closure). Mutates the project block. May emit two JSON objects: project-md upsert + phase-next result.
+
+```bash
+agent-workflow phase-next --code session035
+```
+
+## stack
+
+Detect the project stack — language, framework, database, build tool — by scanning the project root.
+
+```bash
+agent-workflow stack
+agent-workflow stack --project-dir /Users/me/Git/some-repo
+```
+
+## workflows
+
+Dump registered specialty workflows. Empty when no flow plugin is loaded; useful for diagnostics.
+
+```bash
+agent-workflow workflows
+```
+
+## skill-index
+
+Lazy-load the skill index of the host plugin (frontmatter only — does not load skill bodies).
+
+```bash
+agent-workflow skill-index --plugin-root /Users/me/Git/core-workflow-plugin
+agent-workflow skill-index --plugin-root /path --flow dev
+agent-workflow skill-index --plugin-root /path --exported-only
+```

package/skills/agent-workflow/references/self.md

@@ -0,0 +1,68 @@
+# Self — manage the CLI itself
+
+`agent-workflow self <subcommand>` covers tasks that target the CLI binary itself: namespace inspection, install diagnostics, in-place upgrade, and skill installation.
+
+```bash
+agent-workflow self <namespace|doctor|update|install-skill>
+```
+
+## self namespace
+
+Print the resolved namespace and the source it came from (env / flag / config / default).
+
+```bash
+agent-workflow self namespace
+
+# Result:
+# { "namespace": "qtc", "source": "env", "expected_paths": { "user_dir": "~/.qtc", "workspace": ".qtc" } }
+```
+
+Use this when paths look wrong — it tells you exactly which override won the precedence chain.
+
+## self doctor
+
+Health check the CLI install: binary location, Node version, namespace config, expected paths, and whether the skill is installed under `~/.claude/skills/agent-workflow/`.
+
+```bash
+agent-workflow self doctor
+```
+
+Returns a structured report. Non-zero exit when something is broken.
+
+## self update
+
+Wraps `npm install -g @tacuchi/agent-workflow-cli@latest`. Confirms interactively when stdout is a TTY.
+
+```bash
+agent-workflow self update
+```
+
+Skips confirmation in non-TTY contexts. Failures from the underlying `npm` invocation propagate.
+
+## self install-skill
+
+Copy the bundled skill (shipped inside the CLI tarball) to `~/.claude/skills/agent-workflow/`. After installation the skill is auto-discovered by Claude Code on next session start.
+
+```bash
+# Default — copy from the bundled location inside the CLI tarball
+agent-workflow self install-skill
+
+# Override the source (local checkout, fork)
+agent-workflow self install-skill --from /Users/me/Git/agent-workflow-cli/skills/agent-workflow
+
+# Overwrite an existing install
+agent-workflow self install-skill --force
+
+# Print the plan without executing
+agent-workflow self install-skill --dry-run
+```
+
+Flags:
+
+| Flag | Default | Notes |
+|---|---|---|
+| `--from <path>` | bundled location inside the CLI tarball | Accepts a local filesystem path only. Remote URLs are no longer supported — the skill is bundled-only. |
+| `--force` | off | Required to overwrite an existing `~/.claude/skills/agent-workflow/` directory. |
+| `--dry-run` | off | Print the resolved source/destination and exit without copying. |
+
+The installer validates that the source contains a `SKILL.md` with valid frontmatter (`name`, `description`) before copying.

package/skills/agent-workflow/references/session-mgmt.md

@@ -0,0 +1,109 @@
+# Session management
+
+Commands that create, list, resume, and close sessions, plus the consolidated artifact dump.
+
+A session lives at `<workspace>/.<namespace>/sessions/sessionNNN-<flow>-<slug>/` and is registered as a row in `<workspace>/.<namespace>/HISTORY.md` plus an entry in the `<NS>-PROJECT` block of `CLAUDE.md` / `AGENTS.md`.
+
+## sessions
+
+List sessions with state counts and the next correlative number.
+
+```bash
+agent-workflow sessions
+agent-workflow sessions --state active
+agent-workflow sessions --state closed
+agent-workflow sessions --all                # alias of --state all
+agent-workflow sessions --include-legacy     # also walk .claude/.codex legacy folders
+agent-workflow sessions --verbose            # include extra metadata per session
+```
+
+Output (truncated):
+
+```json
+{
+  "namespace": "agent-workflow",
+  "next_number": 36,
+  "active": [{ "code": "session035", "folder": "...", "flow": "dev" }],
+  "closed_count": 34,
+  "total": 35
+}
+```
+
+## session-create
+
+Create a new session: scaffolds the folder, writes a stub `OBJETIVO.md`, adds a row to `HISTORY.md`, and registers the session in the project block. Returns the upserted project block JSON.
+
+```bash
+agent-workflow session-create \
+  --flow dev \
+  --name fix-login-loop \
+  --objetivo "Resolver redirect loop tras login en producción"
+
+# With phased / refactor metadata:
+agent-workflow session-create --flow dev --name normalize-codusuario \
+  --tipo refactor \
+  --branches "core:feature/normalize,solicitud:feature/normalize"
+
+# Origen handoff (this session continues from a previous one):
+agent-workflow session-create --flow dev --name aw-skill-repo \
+  --from "design:034"
+```
+
+Flags:
+
+| Flag | Required | Notes |
+|---|---|---|
+| `--flow <core\|dev\|design\|analyze>` | yes | Determines slug prefix and downstream specialty composition. |
+| `--name <slug>` | yes | Kebab-case; becomes the session slug suffix. |
+| `--objetivo <text>` | yes | Free-form requirement description that lands in `OBJETIVO.md`. |
+| `--branches <alias:branch[,alias:branch]>` | no | Pre-fills the work branch table. |
+| `--from <flow:NNN>` | no | Records origin handoff. |
+| `--tipo <feature\|refactor\|bugfix>` | no | Persisted in `OBJETIVO.md` for dev sessions. |
+| `--modalidad <tecnica\|datos\|incidente>` | no | Persisted for analyze sessions. |
+
+## session-resume
+
+Load the resume payload (objetivo + phase) for a session.
+
+```bash
+agent-workflow session-resume                      # active session in workspace
+agent-workflow session-resume --code session035    # explicit code
+```
+
+Use this for the cold-start flow when you do not have a CHECKPOINT.md yet (newer sessions: prefer `checkpoint-read` + `resume-summary`).
+
+## session-close
+
+Close a session: marks the HISTORY row as closed and removes the entry from `<NS>-PROJECT`. Emits two JSON objects on stdout (project-md upsert first, then close result), mirroring the legacy Python contract.
+
+```bash
+agent-workflow session-close --code session035
+agent-workflow session-close --code session035 \
+  --graduated-decisions "DEC-007,DEC-009" \
+  --graduated-plan "TASKS" \
+  --graduated-scripts "019" \
+  --refs "[CHECKPOINT](.qtc/sessions/session035-dev-aw-skill-repo/CHECKPOINT.md)"
+```
+
+Flags:
+
+| Flag | Notes |
+|---|---|
+| `--code <sessionNNN>` | Required if multiple active sessions. |
+| `--graduated-decisions <list>` | Comma-separated DEC-NNN ids that were promoted to `docs/decisiones/`. |
+| `--graduated-plan <slug>` | Marks plan graduation (typically `TASKS`). |
+| `--graduated-scripts <NNN>` | SQL release bundle correlative if applicable. |
+| `--graduated-design <slug>` | Design entrega graduation. |
+| `--graduated-rfc <slug>` | RFC graduation. |
+| `--refs <markdown>` | Replace the auto-generated Refs cell in HISTORY.md. |
+
+## session-artifacts
+
+Consolidated dump of a session's artifacts (OBJETIVO + TASKS + flags). Useful for prompt context or for debugging when you want everything at once.
+
+```bash
+agent-workflow session-artifacts --code session035
+agent-workflow session-artifacts --code session035 --verbose
+```
+
+Flags: `--code <sessionNNN>`, `--verbose`.

package/skills/agent-workflow/references/sources.md

@@ -0,0 +1,102 @@
+# Sources, branches, project block, multi-root
+
+Workspace state lives in the `<NS>-PROJECT` block of `CLAUDE.md` / `AGENTS.md`. These commands read or update that state, plus surface git context for declared sources.
+
+## sources
+
+List sources from the project block, enriched with git status (current branch, dirty flag, ahead/behind).
+
+```bash
+agent-workflow sources
+agent-workflow sources --no-git                    # skip git enrichment (fast)
+agent-workflow sources --session session035        # constrain to sources of a session
+agent-workflow sources --scope core,dev,design     # filter by alias
+agent-workflow sources --flow dev                  # heuristic source filtering by flow
+agent-workflow sources --verbose
+```
+
+## check-branch
+
+Verify a source branch matches the expected work branch declared in the project block.
+
+```bash
+agent-workflow check-branch --source core                       # by alias
+agent-workflow check-branch --path /Users/me/Git/foo            # by path
+agent-workflow check-branch --file /Users/me/Git/foo/src/x.ts   # by descendant file
+agent-workflow check-branch --source core --strict              # exit 2 on mismatch
+agent-workflow check-branch --source core --session session035
+agent-workflow check-branch --source core --flow dev
+```
+
+Returns `{ match: true|false, expected, current, ... }`. `--strict` makes mismatch cause a non-zero exit.
+
+## workspace-mode
+
+Read the workspace mode (`project` vs `hub`) plus declared sources and current working branches.
+
+```bash
+agent-workflow workspace-mode
+agent-workflow workspace-mode --verbose
+```
+
+`hub` mode means the workspace coordinates ≥2 sources (the project block has a `Mode: hub` marker). Otherwise `project`.
+
+## project-md-upsert
+
+Read or update the `<NS>-PROJECT` block.
+
+```bash
+# Read mode
+agent-workflow project-md-upsert --read
+agent-workflow project-md-upsert --read --verbose
+
+# Init the block (creates it if missing)
+agent-workflow project-md-upsert --init --proyecto "Marketplace" --mode hub
+
+# Add a session entry
+agent-workflow project-md-upsert --add-session sessionNNN-dev-foo \
+  --phase planning --branches "core:feature/foo,dev:feature/foo"
+
+# Update the phase of an existing session
+agent-workflow project-md-upsert --update-phase --add-session sessionNNN-dev-foo --phase execution
+
+# Remove a session
+agent-workflow project-md-upsert --remove-session sessionNNN-dev-foo
+
+# Set a working branch
+agent-workflow project-md-upsert --working-branch "core:feature/custom-CLI"
+```
+
+Operations are mutually exclusive — pick one of `--read | --init | --add-session | --remove-session | --update-phase`.
+
+## upgrade-hub-mode
+
+Detect when ≥2 sources are declared in a workspace stuck in `project` mode and apply the `Mode: hub` upgrade.
+
+```bash
+agent-workflow upgrade-hub-mode --dry-run    # preview only
+agent-workflow upgrade-hub-mode              # apply
+```
+
+## attach-multiroot
+
+Configure multi-root visibility for the host harness (Claude Code + Codex CLI). Useful when a hub workspace coordinates folders that live outside the primary root.
+
+```bash
+agent-workflow attach-multiroot --from-sources                 # use declared sources
+agent-workflow attach-multiroot --path /Users/me/Git/core --path /Users/me/Git/dev
+agent-workflow attach-multiroot --paths "/Users/me/Git/core,/Users/me/Git/dev"
+agent-workflow attach-multiroot --from-sources --global        # write to user-level config
+agent-workflow attach-multiroot --from-sources --workspace foo # named workspace slot
+agent-workflow attach-multiroot --from-sources --skip-codex    # only Claude Code
+```
+
+## detach-multiroot
+
+Reverse of `attach-multiroot`.
+
+```bash
+agent-workflow detach-multiroot --from-sources
+agent-workflow detach-multiroot --path /Users/me/Git/core
+agent-workflow detach-multiroot --global --workspace foo
+```