feat(skills): add agentic workflow design skill

[mogul]

Summary

• Add an experimental meta skill for designing and reviewing multi-step agent workflows.
• Translate the submitted Agentic SI Workflow Design Guide into an agent-usable procedure and output contract.
• Retain the guide's core practices: explicit authority, typed state and data contracts, gate dependencies, deterministic verification, and durable run records.
• Adapt the source material to repository conventions rather than reproducing it as a long policy document.
• Add four behavior test cases and regenerate the pattern catalog.

Origin and Design Rationale

This skill originated from a submitted workflow-design guide that collected practical lessons for operating complex, multi-step agent workflows. The guide was useful as a source of design principles, but it was too long and reference-oriented to load directly as a reusable agent skill.

This contribution converts those principles into a concise operational skill that tells an agent:

1. When workflow design or review is appropriate.
2. Which questions must be answered before the workflow can be considered ready.
3. Which artifacts must be produced, including data contracts, a typed step graph, step specifications, gates, and a verification plan.
4. How to identify incomplete designs, such as a state without a terminal route, a value read without a producer, work that bypasses a gate, or authority that has not been granted.
5. How to return a clear readiness result: PASS, BLOCKED, or NEEDS-REVISION.

The skill intentionally does not implement an orchestration platform, authorize actions, or claim that a workflow is safe to execute. It establishes a reviewable design package that a human and implementation team can use before execution.

The draft also resolves source-material issues that would not be suitable for a repository skill, including removing personal contact information and avoiding broken internal-reference conventions. It uses generic examples and repository-standard frontmatter, routing metadata, safety constraints, and behavioral test cases.

Content Type

• Skill
• Prompt
• Workflow
• Agent instructions
• Lesson learned

Safety Checklist

• No secrets, tokens, credentials, or private keys
• No PII, CUI, customer data, or sensitive information
• No internal URLs or system details
• Examples use generic placeholders
• prohibited_content defined in frontmatter

Quality Checklist

• Frontmatter is complete and valid
• Content is reusable beyond one project
• Prerequisites and authority boundaries are documented
• Verification steps are included
• make validate passes
• Status is experimental
• INDEX.yaml and CATALOG.md regenerated

Verification Transcript

Passed:

• make generate
• make validate
• make test (448 passed)
• make test-cases (77 passed, including 4 new cases)
• make generate-check
• make scan-shell (0 errors, 0 warnings)
• make validate-kits
• make test-kits
• Targeted pre-commit whitespace, YAML, and gitleaks checks
• pip-audit --skip-editable
• git diff --check

Known baseline exception:

• make ci reaches the Ruff pre-commit hook and fails on two intentional vulnerable-code fixtures in .agents/skills/secure-code-review/tests/fixtures/sample-code.py: S608 (SQL injection) and S605 (shell execution). This PR does not modify that fixture. All remaining CI phases that were run independently pass.

Rollback

Revert commit 47897f8 to remove the skill, test cases, and generated catalog entries.

Security Impact

No authentication, authorization, runtime data-handling, or attack-surface changes. The skill improves workflow-planning controls by requiring explicit authority, deterministic verification, durable evidence, and a BLOCKED or NEEDS-REVISION result when approvals or constraints are missing.

AI Assistance

This PR was drafted with OpenCode AI assistance. Human review is required before merge.