{
  "markdown": "# Arsyn\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\nComposable skills that turn coding agents into disciplined engineers.\n\nWorks with **Claude Code**, **Cursor**, **Codex**, and **OpenCode**.\n\n## The Name\n\n**Arsyn** is a constructed word:\n\n- **ars** (Latin) — skill, technique, craft\n- **syn** (Greek prefix) — together, integration, synthesis\n\n*Arsyn* ≈ \"synthesis of skills\" — a composable library of behavioral skills for AI coding agents.\n\n## How It Works\n\nArsyn activates automatically. When your agent encounters a task, it doesn't jump into writing code — it checks for relevant skills first. This is enforced, not suggested.\n\nA typical feature build flows through structured phases: **ideation** → **isolation** → **planning** → **orchestration** → **finalization**. Each phase is a skill that triggers contextually.\n\nSkills use progressive disclosure — the main SKILL.md stays lean while `references/` directories hold detailed guides, templates, and scripts that load only when needed.\n\n## Core Workflow\n\n1. **ideating** — Explores intent through structured questions. Produces an approved design document.\n2. **isolating** — Creates a git worktree on a fresh branch, runs project setup, verifies clean test baseline.\n3. **planning** — Decomposes the design into bite-sized tasks with exact file paths, complete code, and verification steps.\n4. **orchestrating** or **executing** — Dispatches subagents per task with review gates, or runs inline with checkpoints.\n5. **tdd** — Enforces red-green-refactor: failing test → minimal code → commit. No production code without a failing test.\n6. **requesting-review** — Dispatches a code review subagent. Critical issues block progress.\n7. **finalizing** — Verifies tests pass, presents options (merge / PR / keep / discard), cleans up the worktree.\n\n## Skills (19)\n\n### ideating\n\nStructured requirement exploration before any implementation begins.\n\n**How:** Interviews you using `AskUserQuestion` with focused, one-at-a-time questions about requirements, constraints, and success criteria. Presents 2-3 approaches with trade-offs. Produces a design document with confidence-tagged sections.\n\n**When:** Triggers before any creative work — new features, components, architecture changes, or behavioral modifications. Mandatory gateway to planning.\n\n**Bonus:** Integrates with the [playground plugin](https://claude.com/plugins/playground) for visual decisions (UI layouts, color schemes, architecture diagrams).\n\n---\n\n### planning\n\nDecomposes approved designs into granular, executable task sequences.\n\n**How:** Breaks work into bite-sized tasks (2-5 min each). Every task has exact file paths, complete copy-pasteable code, verification commands with expected output, and a commit step. Tasks are confidence-tagged (`HIGH` / `MEDIUM` / `LOW`).\n\n**When:** After a design is approved via ideating. Use when you have a spec or requirements for a multi-step task.\n\n---\n\n### executing\n\nRuns through an implementation plan task-by-task in the current session.\n\n**How:** Loads a plan file, executes tasks sequentially with checkpoint reviews between batches. Stops on failures and reports what went wrong.\n\n**When:** After a plan exists and you choose inline execution (vs. orchestrating). Good for smaller plans or when you want direct oversight.\n\n---\n\n### orchestrating\n\nDistributes plan tasks across fresh subagents with two-stage quality gates.\n\n**How:** Dispatches one subagent per task with isolated context. Each task goes through spec compliance review, then code quality review. Uses `TaskCreate`/`TaskUpdate` for inter-agent coordination and file system for shared state.\n\n**When:** After a plan exists and you choose parallel execution. Recommended for larger plans — fresh context per task prevents drift.\n\n---\n\n### tdd\n\nEnforces red-green-refactor discipline on every implementation.\n\n**How:** Every feature starts with a failing test. You watch it fail, write the minimal code to make it pass, verify it passes, then commit. No production code is written before a test exists for it.\n\n**When:** During any feature or bugfix implementation. Active throughout the entire coding phase.\n\n**Reference:** Includes `references/testing-anti-patterns.md` for common testing mistakes.\n\n---\n\n### debugging\n\nRoot-cause investigation that eliminates guesswork.\n\n**How:** Four-phase protocol: observe symptoms → trace to immediate cause → form and test hypotheses → implement targeted fix. Writes findings to a `debug-log.md` file so you can grep across them instead of losing context.\n\n**When:** Any bug, test failure, or unexpected behavior — before proposing fixes. Prevents the \"try random changes until it works\" pattern.\n\n**References:** `references/root-cause-tracing.md`, `references/defense-in-depth.md`, `references/condition-based-waiting.md`\n\n---\n\n### verifying\n\nEnforces evidence-based completion claims.\n\n**How:** Pre-flight checklist before any \"done\" claim: run tests, run linter, run build, check requirements, check edge cases, check git status. Every claim maps to a verification command with expected output.\n\n**When:** Before claiming work is complete, before committing, before creating PRs. Catches \"it works on my machine\" and \"I'm pretty sure it passes\" claims.\n\n---\n\n### isolating\n\nCreates isolated git worktrees for feature development.\n\n**How:** Resolves worktree directory (existing > CLAUDE.md directive > prompt), verifies `.gitignore` coverage, creates worktree on new branch, auto-detects and runs project setup (npm, cargo, pip, go mod, etc.), runs baseline tests.\n\n**When:** Before starting feature work that needs isolation from the current workspace, or before executing implementation plans.\n\n**Reference:** `references/setup-commands.md` for ecosystem-specific install/test commands.\n\n---\n\n### finalizing\n\nGuides completion of development work.\n\n**How:** Verifies all tests pass, then presents four options: (1) merge locally and clean up worktree, (2) push and create PR, (3) keep branch as-is for later, (4) discard with typed confirmation. Handles cleanup automatically.\n\n**When:** When implementation is complete and all tests pass. The last step in the core workflow.\n\n---\n\n### requesting-review\n\nDispatches a code review subagent to audit completed work.\n\n**How:** Gathers git SHAs for the work range, dispatches a read-only code-reviewer subagent with structured template. Reviewer categorizes issues as Critical / Important / Minor. Critical issues block progress.\n\n**When:** After completing a task or feature, before merging. Required between orchestrated subagent tasks.\n\n**Reference:** `references/code-reviewer.md` for the review template.\n\n---\n\n### handling-review\n\nProcesses code review feedback with technical rigor.\n\n**How:** Six-step protocol: read → understand → verify → evaluate → respond → implement. Verifies each suggestion technically before accepting. Rejects performative agreement (\"You're absolutely right!\"). Applies YAGNI filter to suggested additions.\n\n**When:** After receiving code review feedback, before implementing suggestions. Especially important when feedback seems unclear or technically questionable.\n\n---\n\n### parallelizing\n\nDispatches independent tasks to concurrent subagents.\n\n**How:** One agent per independent problem domain. Each gets a structured prompt (scope, context, constraints, deliverable). Results are reviewed and integrated after all agents complete.\n\n**When:** Facing 2+ independent tasks that share no state — batch file processing, multi-service updates, independent test suites, or parallel research queries.\n\n**Reference:** `references/agent-prompt-template.md` for structuring subagent prompts.\n\n---\n\n### scaffolding\n\nGenerates project scaffolds and module templates.\n\n**How:** Detects existing codebase conventions (framework, language, test runner, lint config), matches to appropriate scaffolding approach, generates with project conventions applied, verifies generated code passes lint and typecheck.\n\n**When:** Creating new projects, services, modules, or components. Prevents generating boilerplate that clashes with existing patterns.\n\n**Reference:** `references/common-scaffolds.md` for templates by pattern type.\n\n---\n\n### runbook\n\nStructured incident investigation from symptoms to root cause.\n\n**How:** Five-phase protocol: intake (capture symptoms, timeline, blast radius) → triage (severity, immediate mitigation) → investigate (evidence gathering, hypothesis testing) → resolve (fix, verify, monitor) → document (post-incident report).\n\n**When:** Production incidents, service outages, alert responses, or error patterns. Integrates with `arsyn:debugging` for deep root-cause analysis.\n\n**Reference:** `references/incident-template.md` for post-incident report format.\n\n---\n\n### guarding\n\nBehavioral guardrails enforced during every implementation task.\n\n**How:** Five rules checked before presenting any result: (1) reasoning-action coherence — code matches analysis, (2) no fabrication — nothing claimed without verification, (3) full transparency — limitations and unhandled cases reported, (4) no invented rules — cite actual config, (5) honest difficulty — partial solutions labeled as such.\n\n**When:** Automatically active during any implementation — coding, building, fixing, refactoring, debugging. Always on, not opt-in.\n\n**Reference:** `references/confidence-scale.md` for the HIGH/MEDIUM/LOW tagging system.\n\n**Research basis:** Inspired by [Schoen et al. (2025)](https://arxiv.org/abs/2509.15541) — *\"Stress Testing Deliberative Alignment for Anti-Scheming Training\"*. The paper showed that making models explicitly reason about safety rules before acting reduces covert misaligned behavior from ~13% to ~0.4%. Guarding applies this principle to coding: force explicit reasoning about integrity rules before presenting any implementation result.\n\n---\n\n### auditing\n\nPost-implementation integrity and quality audit.\n\n**How:** Checks 5 integrity criteria (coherence, fabrication, omissions, convention compliance, shortcuts) and 4 technical quality criteria (defects, security, efficiency, clarity). Produces structured JSON report with per-criterion PASS/FAIL and overall verdict: `APPROVED` / `APPROVED_WITH_CAVEATS` / `REJECTED`.\n\n**When:** After implementation is complete. Triggered via `/review` command or when asked to audit, verify, or check completed work.\n\n**Research basis:** Complements guarding by auditing the same failure patterns identified in [Schoen et al. (2025)](https://arxiv.org/abs/2509.15541) — fabrication, omission, and reasoning-action divergence — after implementation rather than during.\n\n---\n\n### precision\n\nMetacognitive calibration for maximum output accuracy.\n\n**How:** Activates a deliberate verification protocol: pause before output, cross-check each claim against evidence, flag uncertainty explicitly, re-verify the final result before presenting.\n\n**When:** Production deployments, data migrations, security changes, financial calculations, or any task where errors are costly. Opt-in when the stakes are high.\n\n---\n\n### skill-crafting\n\nCreates, tests, and refines agent skills using evaluation-driven development.\n\n**How:** Applies TDD to skill writing: define failure scenarios first, write the skill, test against scenarios with subagents, iterate. Incorporates Anthropic's official best practices (conciseness, progressive disclosure, degrees of freedom) and Thariq's principles (description-as-trigger, gotchas-first, evaluation-driven).\n\n**When:** Creating new skills, editing existing skills, or verifying skills work before deployment.\n\n**References:** `references/anthropic-best-practices.md`, `references/thariq-skill-categories.md`, `references/search-optimization.md`\n\n---\n\n### bootstrapping\n\nSession-start skill discovery protocol.\n\n**How:** Injected into every conversation via the session-start hook. Establishes the core rule: invoke relevant skills before any response. Provides the skill catalog and instruction priority (user > Arsyn > default system prompt).\n\n**When:** Loaded automatically at session start. You never invoke this manually — it's always present.\n\n---\n\n## Commands\n\n| Command | Purpose |\n|---------|---------|\n| `/ideate` | Start structured ideation session |\n| `/plan` | Create implementation plan from spec |\n| `/execute` | Run through a plan task-by-task |\n| `/review` | Run integrity and quality audit |\n| `/ci` | Run lint, typecheck, test, build in parallel |\n| `/pr` | Create a pull request |\n| `/respond` | Address PR review comments |\n| `/deslop` | Clean up AI-generated code patterns |\n| `/careful` | Block dangerous commands until deactivated |\n| `/freeze` | Block edits outside specified directories |\n\n## Agents\n\n| Agent | Role |\n|-------|------|\n| **code-reviewer** | Read-only senior code reviewer. Audits completed work against plans and coding standards. |\n| **project-structure-validator** | Validates and fixes project structure against conventions in CLAUDE.md or AGENTS.md. |\n\n## Installation\n\n### Claude Code\n\n```bash\n# Add the marketplace\n/plugin marketplace add renathoaz/arsyn\n\n# Install the plugin\n/plugin install arsyn@renathoaz\n```\n\n### Cursor\n\n```bash\ngit clone https://github.com/renathoaz/arsyn ~/.cursor/plugins/arsyn\n```\n\nRestart Cursor to load the plugin.\n\n### Codex\n\n```bash\ngit clone https://github.com/renathoaz/arsyn ~/.codex/arsyn\nmkdir -p ~/.agents/skills\nln -s ~/.codex/arsyn/skills ~/.agents/skills/arsyn\n```\n\nRestart Codex to discover the skills.\n\n### OpenCode\n\nAdd to your `opencode.json`:\n\n```json\n{\n  \"plugin\": [\"arsyn\"]\n}\n```\n\nRestart OpenCode. The plugin auto-installs and registers all skills.\n\nSee platform-specific guides: [Codex](.codex/INSTALL.md) · [OpenCode](.opencode/INSTALL.md)\n\n## Design Principles\n\nBuilt on lessons from [Thariq's \"How We Use Skills\"](https://x.com/trq212/status/2033949937936085378) and the [Anthropic skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices):\n\n- **Progressive disclosure** — Skills are folders, not just markdown. Heavy content lives in `references/` and loads on demand.\n- **Gotchas-first** — The highest-signal content in any skill is what goes wrong. Every skill has a Gotchas section built from real failure patterns.\n- **Description as trigger** — Skill descriptions define *when* to activate, not what the skill does.\n- **Don't state the obvious** — Only include what pushes the agent beyond its default behavior.\n- **Don't railroad** — Provide information and flexibility. Match specificity to task fragility.\n- **Evidence over claims** — Verify before declaring success.\n- **Integrity first** — No shortcuts, no fabrication, full transparency.\n\n## References\n\n- Schoen, B., Nitishinskaya, E., Balesni, M., et al. (2025). *Stress Testing Deliberative Alignment for Anti-Scheming Training*. arXiv:2509.15541. [https://arxiv.org/abs/2509.15541](https://arxiv.org/abs/2509.15541)\n\n## License\n\n[MIT](LICENSE)\n",
  "bytes": 14955,
  "sha": "45b1ccc54c496f1e79e2eeceb40624e94313093a60308490938a8b4319cf4387",
  "repo_slug": "renathoaz/arsyn",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_renathoaz_arsyn_d62a3b42/readme"
}