bump to v3.4.0-beta

Signed-off-by: ainetx <viator@via-net.org>

Author: ainetx

.agents/skills/cypilot-analyze/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: cypilot-analyze
+description: "Analyze Cypilot artifacts against templates or code against design requirements with traceability verification (tool invocation is validate-only)"
+---
+
+ALWAYS open and follow `{cypilot_path}/.core/workflows/analyze.md`

.agents/skills/cypilot-generate/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: cypilot-generate
+description: "Create/update artifacts or implement code"
+---
+
+ALWAYS open and follow `{cypilot_path}/.core/workflows/generate.md`

.agents/skills/cypilot-plan/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: cypilot-plan
+description: "Decompose large tasks into self-contained phase files"
+---
+
+ALWAYS open and follow `{cypilot_path}/.core/workflows/plan.md`

.agents/skills/cypilot-workspace/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: cypilot-workspace
+description: "Multi-repo workspace setup — discover repos, configure sources, generate workspace config, validate"
+---
+
+ALWAYS open and follow `{cypilot_path}/.core/workflows/workspace.md`

.bootstrap/.core/skills/cypilot/agents.toml

@@ -5,6 +5,21 @@
 #
 # Semantic fields (mode, isolation, model) are mapped to per-tool
 # frontmatter by the agents command — kits never need tool-specific knowledge.
+#
+# Field mappings by tool:
+#
+#   isolation (bool):
+#     Claude Code  → true = worktree-isolated agent, false = main-context agent
+#     Cursor       → true = "agent" mode (background), false = inline composer
+#     Copilot      → true = separate workspace context, false = shared context
+#     Codex        → true = sandboxed execution, false = shared session
+#
+#   model (string):
+#     "inherit"    → all tools: use the model selected by the user/session
+#     "fast"       → Claude Code: maps to "sonnet"; Cursor: kept as "fast";
+#                    Copilot/Codex: maps to the tool's fast-tier model
+#     Prefer "inherit" unless the agent explicitly needs a cheaper/faster tier.
+#     Use "fast" only for high-volume, low-complexity tasks (e.g. PR review).
 
 [agents.cypilot-codegen]
 description = """\

.bootstrap/.core/skills/cypilot/agents/cypilot-phase-runner.md

@@ -17,8 +17,11 @@ Execution rules:
 - Treat `plan.toml` on disk as the sole source of truth.
 - When the user asks to execute a phase, read `plan.toml` first and determine the
   target phase from manifest state unless the user explicitly names a phase.
-- Audit dependencies, declared `output_files`, declared `outputs`, downstream
+- Verify dependencies, declared `output_files`, declared `outputs`, downstream
   `inputs`, and lifecycle-state exceptions exactly as defined in `plan.md`.
+  Verification means: confirm each declared dependency file exists and is
+  non-empty, confirm each declared output path is writable, and confirm
+  downstream `inputs` reference existing or to-be-created outputs.
 - Repair stale lifecycle state exactly when the manifest rules require it before
   continuing execution.
 - Update the selected phase to `in_progress` before execution when the runtime

.bootstrap/.core/skills/cypilot/agents/cypilot-ralphex.md

@@ -5,6 +5,7 @@
 - [CLI Entrypoint](#cli-entrypoint)
 - [Library Entrypoint](#library-entrypoint)
 - [Post-Run Handoff](#post-run-handoff)
+- [Response Completion Gate](#response-completion-gate)
 
 <!-- /toc -->
 
@@ -69,6 +70,16 @@ build command → track lifecycle. It returns a structured dict with keys:
 - `"delegated"` — command assembled and ready for invocation
 - `"error"` — a precondition failed; check the `error` field
 
+**Error handling:** When `result["status"] == "error"`, inspect `result["error"]`
+for the failure reason and `result["lifecycle_state"]` for the lifecycle position.
+Do NOT proceed to Post-Run Handoff. Instead:
+- If `result["bootstrap"]["needed"]` is `True`: inform the user that `ralphex --init`
+  is required and request explicit approval before running it.
+- If `result["error"]` references review precondition failure: report the
+  precondition (e.g. no commits ahead of default branch) and suggest resolution.
+- For all other errors: report the error message, the lifecycle state at failure,
+  and offer retry or abort options.
+
 **Mode selection:**
 
 | Mode | Command | Notes |
@@ -120,9 +131,28 @@ from cypilot.ralphex_export import (
 
 1. Call `read_handoff_status(exit_code, output_refs, partial)` to classify the delegation outcome (success/partial/failed).
 2. Call `check_completed_plans(plans_dir, task_slug)` to inspect the ralphex-managed `completed/` subdirectory for lifecycle artifacts.
-3. Call `run_validation_commands(commands, cwd=repo_root)` with the validation commands from the original Cypilot plan to verify execution correctness independently of ralphex. Pass the delegated repository root as `cwd` so repo-relative commands resolve correctly.
+3. Call `run_validation_commands(commands, cwd=repo_root)` with validation commands
+   extracted from the `## Validation Commands` section of the compiled plan file
+   (`result["plan_file"]`). Each non-empty, non-heading line in that section is one
+   command. Pass the delegated repository root as `cwd` so repo-relative commands
+   resolve correctly.
 4. Call `report_handoff(...)` to assemble the delegation summary.
-5. Return the handoff report to the main conversation with status, output refs, validation outcome, and next-step options.
+5. Return the handoff report to the main conversation using this structured format:
+
+```markdown
+## Delegation Handoff Report
+- **Status**: {report["status"]} (success | partial | failed)
+- **Plan file**: `{report["plan_file"]}`
+- **Mode**: {report["mode"]}
+- **Validation passed**: {report["validation_passed"]}
+- **Completed plan**: `{report["completed_plan_path"]}` or none
+- **Output refs**: {report["output_refs"] as bulleted list, or "none"}
+
+### Next Steps
+1. Review output artifacts listed above
+2. Run `/cypilot-analyze` on changed files if validation passed
+3. If failed: inspect error output, fix issues, and re-delegate
+```
 
 **Bootstrap gate:**
 
@@ -131,3 +161,16 @@ with `bootstrap.needed = True` and a message directing the user to run
 `ralphex --init`. If the user wants to proceed, request explicit approval before
 running `ralphex --init`. NEVER run `ralphex --init` automatically — it is
 always an opt-in action.
+
+## Response Completion Gate
+
+This agent's response is complete only when ALL of the following are true:
+- `run_delegation()` has been called and the result dict is available
+- If `status == "error"`: the error has been reported with lifecycle state,
+  failure reason, and recovery options (retry/abort/bootstrap)
+- If `status != "error"`: Post-Run Handoff steps 1–5 have been executed and
+  the structured Delegation Handoff Report has been emitted
+- The SKILL.md invariant has been satisfied (Cypilot mode was loaded)
+
+Do NOT end the response with only a summary or status update. The handoff
+report (or error report with recovery options) is the mandatory terminal block.

.bootstrap/.core/skills/cypilot/scripts/cypilot/__init__.py

@@ -17,7 +17,7 @@ def main(argv: Optional[List[str]] = None) -> int:
     from .cli import main as _main
     return _main(argv)
 
-__version__ = "v3.3.0-beta"
+__version__ = "v3.4.0-beta"
 
 __all__ = [
     # Main entry point

.bootstrap/.core/skills/cypilot/scripts/cypilot/commands/_core_config.py

@@ -12,7 +12,7 @@
 logger = logging.getLogger(__name__)
 
 # @cpt-begin:cpt-cypilot-algo-ralphex-delegation-discover:p1:inst-read-config
-_ADAPTER_DIRS = (".bootstrap", "cypilot")
+_ADAPTER_DIRS = (".bootstrap", "cypilot", ".cypilot", ".cpt")
 
 
 def load_core_config(project_root: Path) -> dict:

.bootstrap/.core/skills/cypilot/scripts/cypilot/commands/agents.py

@@ -381,32 +381,31 @@ def _agent_template_copilot(agent: Dict[str, Any]) -> List[str]:
 }
 
 
-def _render_toml_agents(agents: List[Dict[str, Any]], target_agent_paths: Dict[str, str]) -> str:
-    """Render one OpenAI Codex TOML role-definition file per agent.
+def _render_toml_agent(agent: Dict[str, Any], target_agent_path: str) -> str:
+    """Render a single OpenAI Codex TOML agent role file.
 
-    Codex treats each ``.toml`` file in ``.codex/agents/`` as a single role
-    definition, so the generated file must expose top-level
-    ``description``/``developer_instructions`` keys rather than nested
-    ``[agents.*]`` tables.
-
-    *agents* must contain exactly one semantic agent dict and *target_agent_paths*
-    must contain its resolved prompt target.
+    Each agent becomes its own ``.toml`` file with top-level ``name``,
+    ``description``, and ``developer_instructions`` — the fields required
+    by the Codex CLI agent-role schema.
     """
-    if len(agents) != 1:
-        raise ValueError("_render_toml_agents() expects exactly one agent for Codex TOML output")
-    agent = agents[0]
     name = agent["name"]
-    desc = " ".join(agent.get("description", "").split())
-    agent_path = target_agent_paths.get(name, "")
-    prompt = f"ALWAYS open and follow `{agent_path}`"
+    raw_desc = agent.get("description", "")
+    if not isinstance(raw_desc, str):
+        raw_desc = str(raw_desc) if raw_desc is not None else ""
+    desc = " ".join(raw_desc.split())
     desc_escaped = desc.replace("\\", "\\\\").replace('"', '\\"')
-    lines: List[str] = [f"# Cypilot subagent definition for OpenAI Codex: {name}", ""]
-    lines.append(f'name = "{name}"')
-    lines.append(f'description = "{desc_escaped}"')
-    lines.append('developer_instructions = """')
-    lines.append(prompt)
-    lines.append('"""')
-    return "\n".join(lines).rstrip() + "\n"
+    prompt = f"ALWAYS open and follow `{target_agent_path}`"
+    lines: List[str] = [
+        f'name = "{name}"',
+        f'description = "{desc_escaped}"',
+        'developer_instructions = """',
+        prompt,
+        '"""',
+    ]
+    return "\n".join(lines) + "\n"
+
+
+
 # @cpt-end:cpt-cypilot-algo-agent-integration-generate-shims:p1:inst-create-proxy-templates
 
 
@@ -630,14 +629,62 @@ def _default_agents_config() -> dict:
                             "path": ".agents/skills/cypilot/SKILL.md",
                             "template": [
                                 "---",
-                                _TMPL_NAME,
+                                "name: cypilot",
                                 _TMPL_DESCRIPTION,
                                 "---",
                                 "",
                                 "{custom_content}",
                                 "ALWAYS open and follow `{target_skill_path}`",
                             ],
-                        }
+                        },
+                        {
+                            "path": ".agents/skills/cypilot-generate/SKILL.md",
+                            "target": "workflows/generate.md",
+                            "template": [
+                                "---",
+                                "name: cypilot-generate",
+                                _TMPL_DESCRIPTION,
+                                "---",
+                                "",
+                                _ALWAYS_FOLLOW_TARGET_PATH,
+                            ],
+                        },
+                        {
+                            "path": ".agents/skills/cypilot-analyze/SKILL.md",
+                            "target": "workflows/analyze.md",
+                            "template": [
+                                "---",
+                                "name: cypilot-analyze",
+                                _TMPL_DESCRIPTION,
+                                "---",
+                                "",
+                                _ALWAYS_FOLLOW_TARGET_PATH,
+                            ],
+                        },
+                        {
+                            "path": ".agents/skills/cypilot-plan/SKILL.md",
+                            "target": "workflows/plan.md",
+                            "template": [
+                                "---",
+                                "name: cypilot-plan",
+                                _TMPL_DESCRIPTION,
+                                "---",
+                                "",
+                                _ALWAYS_FOLLOW_TARGET_PATH,
+                            ],
+                        },
+                        {
+                            "path": ".agents/skills/cypilot-workspace/SKILL.md",
+                            "target": "workflows/workspace.md",
+                            "template": [
+                                "---",
+                                "name: cypilot-workspace",
+                                _TMPL_DESCRIPTION,
+                                "---",
+                                "",
+                                _ALWAYS_FOLLOW_TARGET_PATH,
+                            ],
+                        },
                     ],
                 },
             },
@@ -1255,50 +1302,36 @@ def _process_single_agent(
                 )
 
         if output_format == "toml":
-            filtered_kit_agents = [ka for ka in kit_agents if ka.get("prompt_file_abs")]
-
-            legacy_toml_path = (output_dir / "cypilot-agents.toml").resolve()
-            if legacy_toml_path.is_file():
-                if dry_run:
-                    subagents_result["deleted"].append(legacy_toml_path.as_posix())
-                    subagents_result["outputs"].append({
-                        "path": _safe_relpath(legacy_toml_path, project_root),
-                        "action": "deleted",
-                    })
-                else:
-                    try:
-                        legacy_toml_path.unlink()
-                        subagents_result["deleted"].append(legacy_toml_path.as_posix())
-                        subagents_result["outputs"].append({
-                            "path": _safe_relpath(legacy_toml_path, project_root),
-                            "action": "deleted",
-                        })
-                    except OSError:
-                        subagents_result["errors"].append(
-                            f"failed to delete legacy OpenAI agent config: {_safe_relpath(legacy_toml_path, project_root)}"
-                        )
-
-            for ka in filtered_kit_agents:
+            # Render one TOML file per agent (Codex CLI expects top-level fields per file)
+            for ka in kit_agents:
                 name = ka["name"]
-                target_agent_rel = target_agent_paths.get(name, "")
-                if not target_agent_rel:
+                agent_path = target_agent_paths.get(name, "")
+                if not agent_path:
                     sys.stderr.write(
                         f"WARNING: agent {name!r} has no resolved prompt target, skipping subagent proxy\n"
                     )
                     subagents_result["skipped"] = True
                     subagents_result["skip_reason"] = subagents_result.get("skip_reason", "") or "one or more agents missing prompt target"
                     continue
-                content = _render_toml_agents([ka], {name: target_agent_rel})
-                filename = filename_fmt.format(name=name)
-                out_path = (output_dir / filename).resolve()
+                toml_path = (output_dir / f"{name}.toml").resolve()
+                content = _render_toml_agent(ka, agent_path)
+                _write_or_skip(toml_path, content, subagents_result, project_root, dry_run)
+            # Clean up stale TOML files: legacy combined file and renamed/removed agents
+            desired_toml_names = {f"{ka['name']}.toml" for ka in kit_agents if target_agent_paths.get(ka["name"])}
+            if output_dir.is_dir():
                 try:
-                    out_path.relative_to(output_dir)
-                except ValueError:
-                    subagents_result["errors"].append(
-                        f"agent {name!r} would write outside {output_dir_rel}, skipped"
-                    )
-                    continue
-                _write_or_skip(out_path, content, subagents_result, project_root, dry_run)
+                    for toml_file in output_dir.glob("cypilot*.toml"):
+                        if toml_file.name in desired_toml_names:
+                            continue
+                        rel = _safe_relpath(toml_file, project_root)
+                        subagents_result["outputs"].append({"path": rel, "action": "deleted"})
+                        if not dry_run:
+                            try:
+                                toml_file.unlink()
+                            except OSError:
+                                pass
+                except OSError:
+                    pass
         else:
             # Markdown + YAML frontmatter (claude, cursor, copilot)
             template_fn = tool_cfg.get("template_fn")
@@ -1806,6 +1839,8 @@ def _render_agent_file_actions(
         ui.file_action(path, "created")
     for path in sub.get("updated", []):
         ui.file_action(path, "updated")
+    for path in sub.get("deleted", []):
+        ui.file_action(path, "deleted")
     if sub.get("skipped") and sub.get("skip_reason"):
         ui.substep(f"subagents skipped: {sub.get('skip_reason')}")