@gh-symphony/cli 0.0.20 → 0.0.22

package/README.md

@@ -61,7 +61,7 @@ Navigate to the repository you want to orchestrate, then run:
 gh-symphony workflow init
 gh-symphony workflow init --dry-run
 gh-symphony workflow validate
-gh-symphony workflow preview
+gh-symphony workflow preview --issue owner/repo#123
 ```
 
 The interactive wizard will:
@@ -71,6 +71,8 @@ The interactive wizard will:
 3. Map project status columns to workflow phases (active / wait / terminal)
 4. Generate `WORKFLOW.md` and supporting files in the repository
 
+Project discovery is pagination-aware for larger GitHub accounts, so viewer projects plus organization-owned projects are collected across multiple API pages before the selection prompt. If a discovery safety cap is hit, the wizard keeps the partial list and prints a warning.
+
 Token-only interactive setup is supported:
 
 ```bash
@@ -83,6 +85,18 @@ whether `WORKFLOW.md`, `.gh-symphony/context.yaml`,
 `.gh-symphony/reference-workflow.md`, and runtime skill files would be created,
 updated, or left unchanged, and then exits without modifying the repository.
 
+The same detected environment data is applied to the generated artifacts, so `WORKFLOW.md`, `.gh-symphony/reference-workflow.md`, and the runtime skill templates already include repository-aware validation guidance for the detected package manager, monorepo layout, and explicit validation commands when they exist.
+
+The detector is language-agnostic by default:
+
+- Node repositories: JS lockfiles plus `package.json` `test` / `lint` / `build` scripts
+- Python repositories: `uv.lock`, `poetry.lock`, `pyproject.toml`, `pytest.ini`, `requirements*.txt`
+- Go repositories: `go.mod`
+- Rust repositories: `Cargo.toml`
+- Generic runners: `Makefile`, `justfile`
+
+Examples of generated validation guidance include `make test`, `just build`, `uv run pytest`, `poetry run pytest`, `go test ./...`, and `cargo test` when those commands are the clearest repository entry points. If the repository exposes conflicting signals, the CLI keeps the generic fallback instead of guessing.
+
 ### Customizing Agent Behavior
 
 `gh-symphony workflow init` generates skill files under `.codex/skills/` (or `.claude/skills/` for Claude Code). These skills define how the AI agent handles commits, pushes, pulls, and project status transitions.
@@ -139,6 +153,8 @@ The interactive wizard will:
 4. Optionally customize advanced settings for repository filtering and workspace root directory
 5. Write project configuration to `~/.gh-symphony/`
 
+This wizard uses the same pagination-aware discovery path as `workflow init`, so it can enumerate large personal and organization-backed GitHub accounts more reliably. If the CLI stops at a safety limit, it warns that the visible project list may be incomplete.
+
 Token-only non-interactive setup:
 
 ```bash
@@ -156,6 +172,8 @@ export GITHUB_GRAPHQL_TOKEN=ghp_your_classic_token
 gh-symphony project add
 ```
 
+If the selected GitHub Project is brand new and has no linked repositories yet, the setup still succeeds. The completion message reports `0 repositories` and suggests either `gh-symphony repo add <owner/name>` or adding a repo-linked issue to the GitHub Project.
+
 ### Project Management
 
 ```bash
@@ -163,16 +181,62 @@ gh-symphony doctor                   # Validate local prerequisites, auth, confi
 gh-symphony doctor --fix             # Apply safe fixes and guide/launch follow-up recovery commands
 gh-symphony project list             # List all configured projects
 gh-symphony project remove <id>      # Remove a project
+gh-symphony project explain owner/repo#123  # Explain why one issue is not dispatching
+gh-symphony repo add owner/name      # Validate and save a repo target manually
 gh-symphony repo sync                # Add newly linked repositories from the GitHub Project
 gh-symphony repo sync --dry-run      # Preview linked repository drift
 gh-symphony repo sync --prune        # Remove local repositories no longer linked
 ```
 
+Use `gh-symphony repo add owner/name` as the onboarding safety check when a
+project starts empty or when you want to register a repository before it is
+linked on the GitHub Project board. Successful validation stores the canonical
+clone URL from the GitHub API. If auth is unavailable or the API is offline,
+the CLI still saves the repo with the fallback HTTPS clone URL and prints a
+warning that validation was skipped.
+
 Use `gh-symphony repo sync` when the GitHub Project board has gained or lost
 linked repositories since the project was first added locally. Default sync is
 additive; `--prune` switches to strict alignment, and `--json` prints the added,
 removed, unchanged, and final repository sets.
 
+For empty projects, use `gh-symphony repo add owner/name` after setup to seed the local repository list without re-running the whole wizard.
+
+### Why Is My Issue Not Running?
+
+Use `gh-symphony project explain <owner/repo#number>` before digging through
+logs manually:
+
+```bash
+gh-symphony project explain owner/repo#123
+gh-symphony project explain owner/repo#123 --json
+gh-symphony project explain owner/repo#123 --workflow ./WORKFLOW.md
+```
+
+The command checks project repository linkage, GitHub Project item presence,
+`WORKFLOW.md` active / wait / terminal state mapping, blocker state, existing
+run / retry / convergence ownership, and project or per-state concurrency
+limits.
+
+If the project has no previous local run snapshot and the repository path is
+not stored in the managed project config, pass `--workflow` so the command
+does not guess from the current shell directory.
+
+```text
+Issue dispatch explanation: owner/repo#123
+Not dispatchable: Issue has 1 unresolved blocker.
+
+Checks:
+  ✓ Repository owner/repo is linked to the active managed project.
+  ✓ Issue is present in the bound GitHub Project item set.
+  ✓ Project state "Todo" maps to an active state in WORKFLOW.md.
+  ✗ Issue has 1 unresolved blocker.
+    Hint: Move blocker issues to a terminal state or update the blocker relationship in GitHub.
+```
+
+The remediation hints point to existing commands such as `workflow preview`,
+`doctor`, `project status`, and `logs --issue`.
+
 ## 4. Run the Orchestrator
 
 ### Foreground
@@ -251,7 +315,7 @@ JSON output includes the resolved auth source as `env` or `gh`.
 Setup:
   workflow init       Interactive repository setup wizard
   workflow validate   Parse and strictly validate WORKFLOW.md
-  workflow preview    Render the final worker prompt from a sample issue
+  workflow preview    Render the final worker prompt from a sample or live issue
   doctor              Run diagnostics and optional first-run remediation
   config show         Show current configuration
   config set          Set a configuration value