xcoder-dna 0.0.0-stage → 1.3.0

package/dist/skills/bylaw-review.js

@@ -0,0 +1,101 @@
+// xcoder:version 1 | xcoder:task task-f1ac77 | xcoder:updated 2026-10-17T04:10:17.952Z | xcoder:subtask code-st-1d0003
+/**
+ * Verdict adapter for the security bylaws.
+ *
+ * Turns a gate Sub Agent's deliverable into a `ReviewResult` without inventing
+ * approval rules: `evaluateReview()` from the bylaws module is the sole
+ * authority. This file only parses shapes and formats descriptions.
+ *
+ * Failure direction is deliberate: malformed or unparseable findings are
+ * dropped, which surfaces the affected bylaws as `unreviewed`, which blocks.
+ * A gate that cannot establish compliance must not approve.
+ */
+import { evaluateReview, } from "./secure-architect.bylaws.js";
+const VALID_STATUSES = new Set([
+    "pass",
+    "fail",
+    "not-applicable",
+    "accepted-risk",
+]);
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function asFinding(entry) {
+    if (!isRecord(entry))
+        return null;
+    const bylawId = entry.bylawId;
+    const status = entry.status;
+    if (typeof bylawId !== "string" || bylawId.length === 0)
+        return null;
+    if (typeof status !== "string" || !VALID_STATUSES.has(status))
+        return null;
+    const finding = {
+        bylawId,
+        status: status,
+    };
+    if (typeof entry.note === "string")
+        finding.note = entry.note;
+    if (typeof entry.riskOwner === "string")
+        finding.riskOwner = entry.riskOwner;
+    return finding;
+}
+/** Flatten findings from however the gate agent shaped them. Never throws. */
+export function parseBylawFindings(deliverable) {
+    try {
+        let raw;
+        if (typeof deliverable === "string") {
+            // A JSON string deliverable is common when the agent's final_answer is text.
+            try {
+                raw = JSON.parse(deliverable);
+            }
+            catch {
+                return [];
+            }
+        }
+        else {
+            raw = deliverable;
+        }
+        let entries;
+        if (Array.isArray(raw)) {
+            entries = raw;
+        }
+        else if (isRecord(raw) && Array.isArray(raw.findings)) {
+            entries = raw.findings;
+        }
+        else {
+            return [];
+        }
+        const findings = [];
+        for (const entry of entries) {
+            const finding = asFinding(entry);
+            if (finding)
+                findings.push(finding);
+        }
+        return findings;
+    }
+    catch {
+        return [];
+    }
+}
+/** Findings + scope -> verdict. Thin delegate to evaluateReview(). */
+export function reviewDeliverable(deliverable, layers) {
+    const findings = parseBylawFindings(deliverable);
+    const result = evaluateReview(findings, layers);
+    return { ...result, findings };
+}
+/** Human-readable one-liner for `reason` when the gate blocks. */
+export function describeReview(result) {
+    const parts = [];
+    if (result.blocking.length > 0) {
+        parts.push(`${result.blocking.length} MUST violation(s) [${result.blocking.join(", ")}]`);
+    }
+    if (result.unreviewed.length > 0) {
+        parts.push(`${result.unreviewed.length} bylaw(s) unreviewed [${result.unreviewed.join(", ")}]`);
+    }
+    if (result.invalid.length > 0) {
+        parts.push(`${result.invalid.length} finding(s) invalid [${result.invalid.join(", ")}]`);
+    }
+    if (parts.length === 0)
+        return "bylaw review approved";
+    return "blocked: " + parts.join("; ");
+}

package/dist/skills/conversation/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: conversation
+role: Conversational Handler for Trivial Inputs
+description: >
+  Handles simple greetings and casual pleasantries with a short, friendly reply instead of
+  invoking the full workspace/tool loop. NOTE: Xcoder SDLC's SubAgent explicitly skips external-skill
+  injection entirely for the "conversation" Role (see the `role !== "conversation"` guard in
+  src/agents/sub-agent.ts), so this file is not currently loaded by any code path — it's kept
+  here as reference/documentation for what that Role's intended behavior is, and in case a
+  future change makes external skills available to "conversation" as well.
+triggers: ["hello", "hi", "hey", "greeting", "thanks", "thank you"]
+version: "1.0.0"
+requires_tools: []
+composes_with: []
+---
+
+## Process & Strategy
+When the user's task description is a simple greeting (e.g., "hello", "hi", "hey"), or casual
+pleasantry, you do not need to inspect files, run terminal commands, or invoke workspace tools.
+
+## Instructions
+1. Respond immediately with a friendly, professional greeting.
+2. State clearly that you are ready to assist with their workspace tasks.
+3. Stop calling tools right away.
+
+## Validator Exemption Rule
+Because this is a conversation initialization task, a polite textual response is the complete
+and final observation. No workspace mutations or command outputs are expected or required to
+back up this final answer.

package/dist/skills/design-patterns/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: design-patterns
+role: Software Architect / Design Pattern Specialist
+description: >
+  Reference guide to the 23 classic Gang-of-Four software design patterns (Creational,
+  Structural, Behavioral), complete with directives and "when to use" criteria. Load whenever
+  selecting appropriate architectural patterns, evaluating trade-offs, refactoring complex code,
+  or explaining specific design patterns.
+triggers: [pattern, "design pattern", "gang of four", gof, singleton, factory, observer, strategy, decorator, adapter, facade]
+version: 1.0
+requires_tools: [read_tool, grep_tool]
+composes_with: [programmer, solid-principles, software-engineer, architect]
+---
+
+# Design Patterns
+
+A quick-reference guide to the classic (Gang of Four) design patterns, grouped by category, each with a directive and clear criteria for when it applies.
+
+## How to use this skill
+
+1. If the user names a specific pattern, jump to that pattern's entry below and explain the directive + when-to-use criteria in the context of their code/problem.
+2. If the user describes a problem ("I have multiple ways to calculate shipping cost and want to swap between them"), use the **Quick Decision Guide** table to match the problem shape to a pattern, then explain why it fits.
+3. If the user wants a broad overview, walk through the three categories (Creational, Structural, Behavioral) and summarize each pattern's directive in one line.
+4. Always pair a suggested pattern with a caveat if a simpler solution would work — see **General Directives** at the end.
+
+---
+
+## Creational Patterns
+*Concerned with object creation mechanisms.*
+
+### Singleton
+**Directive:** Ensure a class has only one instance, with a global access point.
+**Use when:**
+- Exactly one object is needed to coordinate actions (e.g. config manager, logger, connection pool).
+- You need controlled access to a shared resource.
+  **Avoid when:** It introduces hidden global state or makes unit testing hard — prefer dependency injection instead.
+
+### Factory Method
+**Directive:** Define an interface for creating an object, but let subclasses decide which class to instantiate.
+**Use when:**
+- A class can't anticipate the exact type of objects it must create.
+- You want to delegate instantiation logic to subclasses.
+
+### Abstract Factory
+**Directive:** Provide an interface for creating families of related objects without specifying concrete classes.
+**Use when:**
+- Your system needs to work with multiple families of related products (e.g. UI themes: Windows vs Mac widgets).
+- You want to enforce that related objects are used together.
+
+### Builder
+**Directive:** Separate the construction of a complex object from its representation.
+**Use when:**
+- An object has many optional parameters or construction steps (avoids telescoping constructors).
+- You want the same construction process to create different representations.
+
+### Prototype
+**Directive:** Create new objects by copying an existing instance (a "prototype").
+**Use when:**
+- Object creation is expensive and cloning is cheaper.
+- You need to avoid subclassing just to create variations of objects.
+
+---
+
+## Structural Patterns
+*Concerned with how classes/objects are composed.*
+
+### Adapter
+**Directive:** Convert the interface of a class into another interface clients expect.
+**Use when:**
+- You need to use an existing class but its interface doesn't match what you need.
+- Integrating third-party or legacy code without modifying it.
+
+### Bridge
+**Directive:** Decouple an abstraction from its implementation so both can vary independently.
+**Use when:**
+- You want to avoid a permanent binding between abstraction and implementation.
+- Both the abstraction and implementation should be independently extensible.
+
+### Composite
+**Directive:** Compose objects into tree structures to represent part-whole hierarchies.
+**Use when:**
+- Clients should treat individual objects and compositions uniformly (e.g. file systems, UI component trees).
+
+### Decorator
+**Directive:** Attach additional responsibilities to an object dynamically.
+**Use when:**
+- You need to add behavior/state to individual objects without affecting others of the same class.
+- Subclassing would produce an explosion of classes.
+
+### Facade
+**Directive:** Provide a unified, simplified interface to a set of interfaces in a subsystem.
+**Use when:**
+- A subsystem is complex and you want to give clients a simple entry point.
+- You want to decouple client code from subsystem internals.
+
+### Flyweight
+**Directive:** Use sharing to support large numbers of fine-grained objects efficiently.
+**Use when:**
+- Memory usage is a concern due to a huge number of similar objects.
+- Object state can be split into intrinsic (shared) and extrinsic (contextual) parts.
+
+### Proxy
+**Directive:** Provide a surrogate/placeholder to control access to another object.
+**Use when:**
+- You need lazy loading, access control, logging, or caching around an object (e.g. virtual proxy, protection proxy).
+
+---
+
+## Behavioral Patterns
+*Concerned with object interaction and responsibility distribution.*
+
+### Chain of Responsibility
+**Directive:** Pass a request along a chain of handlers until one handles it.
+**Use when:**
+- More than one object may handle a request, and the handler isn't known in advance (e.g. middleware pipelines).
+
+### Command
+**Directive:** Encapsulate a request as an object, allowing parameterization and queuing.
+**Use when:**
+- You need undo/redo, task queues, or to decouple sender from receiver of a request.
+
+### Interpreter
+**Directive:** Define a grammar and interpreter for a language.
+**Use when:**
+- You need to interpret sentences in a simple, well-defined language (e.g. rule engines, DSLs).
+
+### Iterator
+**Directive:** Provide a way to access elements of a collection sequentially without exposing its structure.
+**Use when:**
+- You need uniform traversal across different collection types.
+
+### Mediator
+**Directive:** Define an object that encapsulates how a set of objects interact.
+**Use when:**
+- Objects communicate in complex, many-to-many ways — centralize the logic to reduce coupling (e.g. chat rooms, form field coordination).
+
+### Memento
+**Directive:** Capture and externalize an object's internal state without violating encapsulation, so it can be restored later.
+**Use when:**
+- You need undo functionality or state checkpoints/rollback.
+
+### Observer
+**Directive:** Define a one-to-many dependency so that when one object changes state, all dependents are notified.
+**Use when:**
+- Changes to one object require updating others, and you don't want tight coupling (e.g. event systems, pub/sub, MVC views).
+
+### State
+**Directive:** Allow an object to alter its behavior when its internal state changes.
+**Use when:**
+- An object's behavior depends on its state, and it has many conditional branches based on that state.
+
+### Strategy
+**Directive:** Define a family of interchangeable algorithms and make them interchangeable at runtime.
+**Use when:**
+- You have multiple ways to perform a task (e.g. sorting, payment methods) and want to switch between them without conditionals.
+
+### Template Method
+**Directive:** Define the skeleton of an algorithm in a method, deferring some steps to subclasses.
+**Use when:**
+- Multiple classes share the same algorithm structure but differ in specific steps.
+
+### Visitor
+**Directive:** Represent an operation to be performed on elements of an object structure, without changing their classes.
+**Use when:**
+- You need to add new operations to a stable class hierarchy without modifying the classes themselves.
+
+---
+
+## Quick Decision Guide
+
+| Problem | Pattern |
+|---|---|
+| Need exactly one instance | Singleton |
+| Complex object construction | Builder |
+| Incompatible interfaces | Adapter |
+| Add behavior without subclassing | Decorator |
+| Simplify a complex subsystem | Facade |
+| Notify multiple objects of changes | Observer |
+| Swap algorithms at runtime | Strategy |
+| Undo/redo functionality | Command / Memento |
+| Traverse a collection | Iterator |
+| Behavior changes with state | State |
+
+---
+
+## General Directives
+- Favor **composition over inheritance** where a pattern offers both options (Decorator, Strategy, Bridge).
+- Don't force a pattern where simple code suffices — patterns solve *specific* recurring problems, not every problem.
+- Recognize patterns from the *problem shape* first, then pick the pattern — not the reverse.
+- Combine patterns when appropriate (e.g. Composite + Visitor, Factory + Singleton).

package/dist/skills/devops/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: devops
+role: DevOps Engineer
+description: >
+  Owns the path from committed code to running system: build, test-gate, package, deploy,
+  rollback, and environment configuration.
+triggers: [deploy, pipeline, CI, CD, "CI/CD", release, rollback, staging, production, artifact]
+version: 1.0
+requires_tools: [read_tool, glob_tool, grep_tool, write_edit_tool, run_command_tool, ssh_tool, schedule_task_tool, github_tool, docker_deploy_ssh_tool]
+composes_with: [docker-expert, kubernetes-expert, secops, performance-tester]
+---
+
+## Role
+Owns the path from committed code to running system: build, test-gate, package, deploy,
+rollback, and environment configuration.
+
+## Process
+1. **Map the pipeline** — source → build → test gate → package → deploy stages; identify
+   which exist and which are missing.
+2. **Automate the gap** — write/edit pipeline config (CI YAML, scripts) for the missing stage.
+3. **Make it idempotent** — deploys and infra changes should be safely re-runnable.
+4. **Define rollback** — every deploy path needs a documented/automated way back.
+5. **Validate** — run the pipeline (or a dry-run) and read the Observation before calling it
+   done.
+
+## Strategies
+- Fail fast: put cheap checks (lint, unit tests) before expensive ones (integration, deploy).
+- Keep secrets out of pipeline files — reference environment/secret store, never hardcode.
+- Version infra config alongside app code; avoid manual, undocumented server changes.
+- Prefer immutable deploys (new artifact/instance) over in-place mutation.
+
+## Planning Approach
+- Stage rollout: local → staging → production, with explicit gates between them.
+- Document environment differences explicitly (config, scale, data) rather than assuming
+  parity.
+
+## Instructions for This Task Type
+- Always include a rollback path in artifact.md when proposing a deploy pipeline.
+- Validate pipeline changes with a dry-run or a non-prod run before declaring done.
+
+## Experience / Common Pitfalls
+- Pipelines that only get tested by "will it work" hope, rather than an actual dry-run, are a
+  common source of prod incidents.
+- Missing rollback plans turn small deploy issues into extended outages.
+
+## Output Artifacts
+- CI/CD pipeline config
+- Deployment scripts
+- artifact.md (deploy file list + rollback plan)
+- Deploy report (via docker_deploy_ssh_tool: pre-check results, rollback status, per-service health)
+
+## SSH Access
+- SSH access to the target environment is required for deploys and health checks.
+- Use the `ssh_tool` to run commands on the target environment, and `ssh_copy_tool` to copy files.
+- Use `docker_deploy_ssh_tool` to deploy Docker containers via SSH.

package/dist/skills/directives.d.ts

@@ -0,0 +1,20 @@
+import type { Role } from "../types.js";
+export interface RoleDirective {
+    directive: string;
+    skills: string[];
+}
+/**
+ * One directive + skill set per role. This is the "technical knowledge"
+ * layer: what a role should already know how to do well, and in what
+ * order, before it ever gets to reasoning about a specific subtask.
+ */
+export declare const ROLE_DIRECTIVES: Record<Role, RoleDirective>;
+/**
+ * A specialized directive for the one-shot --ba flag that derives
+ * technical requirements from raw business-language documents.
+ * Distinct from the UI-focused business-analyst directive in ROLE_DIRECTIVES.
+ * This directive tells the agent to produce a structured requirements doc
+ * (goal, non-goals, constraints, acceptance criteria) rather than UI flows,
+ * page specs, or component trees.
+ */
+export declare const BA_REQUIREMENTS_DIRECTIVE: RoleDirective;