xcoder-dna 0.0.0-stage → 1.3.0

package/dist/skills/enterprise-systems-analyst/references/hcm.md

@@ -0,0 +1,38 @@
+# HCM (Human Capital Management)
+
+## What it is
+Manages the employee lifecycle from recruiting through offboarding — broader than "payroll software," covering talent acquisition, core HR records, performance, and workforce planning.
+
+## Core functional areas
+- **Core HR/HRIS** — employee records, org charts, position management, compliance documentation.
+- **Recruiting (ATS – Applicant Tracking System)** — job requisitions, candidate pipeline, interview scheduling, offer management.
+- **Payroll** — pay calculation, tax withholding/filing, direct deposit, payslips; often region-specific due to tax/labor law.
+- **Benefits Administration** — enrollment, eligibility rules, carrier integration (health, retirement, etc.).
+- **Performance Management** — goal setting, reviews, 360 feedback, calibration.
+- **Learning Management (LMS)** — training assignment and completion tracking, often compliance-driven.
+- **Workforce Planning/Analytics** — headcount planning, turnover analysis, DEI reporting.
+
+## Major vendors (landscape, not endorsements)
+- **Enterprise:** Workday, SAP SuccessFactors, Oracle HCM Cloud
+- **Mid-market/SMB:** BambooHR, Rippling, Gusto, ADP Workforce Now
+
+## Common BA tasks
+- Documenting the hire-to-retire process end-to-end, noting where handoffs between recruiting → onboarding → payroll → benefits currently break down.
+- Defining approval workflows for org changes (promotions, transfers, terminations) and who is authorized at each step.
+- Specifying compliance requirements (varies heavily by jurisdiction — e.g. FLSA classification in the US, working time directives in the EU) — always confirm with legal/compliance, don't assume.
+- Mapping payroll integration requirements (time & attendance system → payroll, benefits carrier files).
+
+## Common pain points driving HCM projects
+- Employee data duplicated/inconsistent across recruiting, HRIS, and payroll systems.
+- Manual, error-prone benefits enrollment and payroll processing.
+- No self-service — HR fielding routine requests (address changes, pay stub requests) manually.
+- Poor visibility into headcount/turnover for workforce planning.
+
+## Sample requirements (illustrative)
+- *"As an HR Coordinator, I want new hire data entered once in the ATS to auto-populate the HRIS record, so that we eliminate duplicate data entry and transcription errors."*
+- *"As a Payroll Manager, I want approved time-and-attendance data to feed payroll automatically, so that manual entry errors don't cause pay discrepancies."*
+- *"As an Employee, I want self-service access to update my address and view pay stubs, so that I don't need to submit a request to HR for routine changes."*
+
+## Terminology notes
+- "Position" vs. "Employee" — a position can exist (and be budgeted) even when vacant; conflating the two in requirements causes headcount reporting errors.
+- Compliance/legal requirements in HCM are jurisdiction-specific — always flag this as a "confirm with legal" item rather than assuming a rule from one country/state applies elsewhere.

package/dist/skills/enterprise-systems-analyst/references/mrp.md

@@ -0,0 +1,37 @@
+# MRP (Material Requirements Planning)
+
+## What it is
+A production planning method that calculates what materials/components are needed, how many, and when — working backward from a production plan through the Bill of Materials. Often a module inside ERP rather than a standalone system today.
+
+## MRP I vs. MRP II
+- **MRP I** — narrowly calculates material needs: what to order/produce and when, based on demand and lead times.
+- **MRP II (Manufacturing Resource Planning)** — expands MRP I to include capacity planning, scheduling, and financial integration — essentially a superset covering the full manufacturing resource picture (materials AND capacity AND cost).
+
+## Core concepts
+- **BOM (Bill of Materials)** — the recipe: what components/sub-assemblies make up a finished item, and in what quantity. Can be multi-level (a sub-assembly has its own BOM).
+- **MPS (Master Production Schedule)** — the plan for what finished goods to build and when; the primary input to MRP.
+- **Lead Time** — time between placing an order (purchase or production) and having the material available. MRP nets this against need dates to determine "order by" dates.
+- **Lot Sizing** — the rule for how much to order/produce at once (e.g. lot-for-lot, fixed order quantity, economic order quantity/EOQ, period order quantity).
+- **Safety Stock** — buffer inventory to absorb demand/supply variability.
+- **Net Requirements Calculation** — Gross requirement (from MPS/BOM explosion) minus on-hand inventory minus scheduled receipts = net requirement to plan.
+- **Capacity Requirements Planning (CRP)** — checks whether planned production is actually feasible given machine/labor capacity — the "II" in MRP II.
+
+## Common BA tasks
+- Documenting BOM accuracy requirements and change-control process (BOM errors cascade into every planning run).
+- Defining lot-sizing rules per item class (e.g. high-value items lot-for-lot to minimize excess inventory; low-value items in larger batches).
+- Mapping lead time data ownership (who updates it, how often) — stale lead times are a top cause of bad MRP output.
+- Specifying exception/alert requirements (e.g. flag when a planned order date is in the past — "past due" exceptions).
+
+## Common pain points driving MRP projects
+- Manual, spreadsheet-based planning that can't keep pace with SKU/BOM complexity.
+- Chronic stockouts or excess inventory from poor lead-time or lot-sizing data.
+- Planners "gut-feel" overriding system recommendations because they don't trust the data (usually a data-quality problem, not a tool problem).
+- No visibility into whether a plan is actually achievable given capacity (missing CRP).
+
+## Sample requirements (illustrative)
+- *"As a Production Planner, I want the system to explode a multi-level BOM automatically when I plan a finished good, so that component-level requirements are generated without manual calculation."*
+- *"As a Purchasing Agent, I want planned purchase orders flagged when they fall within an item's lead time window, so that I know which need to be released urgently."*
+- *"As a Plant Manager, I want capacity checks against the MPS before it's finalized, so that we don't commit to a schedule the shop floor can't achieve."*
+
+## Terminology notes
+- Don't confuse MRP's "order" (a planned/actual production or purchase order) with a CRM sales order or ERP's customer sales order — related but distinct objects, often linked via the sales order → MPS → MRP chain.

package/dist/skills/enterprise-systems-analyst/references/scm.md

@@ -0,0 +1,32 @@
+# SCM (Supply Chain Management)
+
+## What it is
+Manages the end-to-end flow of goods, information, and money from raw material sourcing through production to final delivery to the customer — broader than MRP (which is production-planning-focused) or pure procurement.
+
+## Core functional areas
+- **Procurement/Sourcing** — supplier selection, contracts, purchase order lifecycle.
+- **Demand Planning/Forecasting** — predicting future demand to drive inventory and production decisions.
+- **Sales & Operations Planning (S&OP)** — cross-functional process balancing demand, supply, and financial plans, typically monthly.
+- **Warehouse Management (WMS)** — receiving, put-away, picking, packing, shipping, cycle counting.
+- **Transportation/Logistics Management (TMS)** — carrier selection, routing, freight optimization, shipment tracking.
+- **Supplier Relationship Management (SRM)** — supplier performance scorecards, risk monitoring.
+
+## Common BA tasks
+- Mapping the physical and information flow end-to-end (as-is) before proposing changes — SCM problems often span multiple systems and departments.
+- Defining demand forecasting inputs/method (statistical forecast vs. sales input vs. hybrid) and accuracy KPIs (e.g. MAPE — mean absolute percentage error).
+- Documenting warehouse process flows (receiving to putaway to pick/pack/ship) to identify bottlenecks before selecting/configuring a WMS.
+- Specifying supplier onboarding and performance evaluation criteria (on-time delivery %, quality reject rate).
+
+## Common pain points driving SCM projects
+- Poor demand forecast accuracy leading to stockouts or excess inventory.
+- No end-to-end shipment visibility — customers/CS can't answer "where's my order."
+- Siloed planning — sales, ops, and finance working off different numbers (no S&OP process).
+- Manual warehouse processes causing pick errors and slow fulfillment.
+
+## Sample requirements (illustrative)
+- *"As a Demand Planner, I want statistical forecasts blended with sales team overrides, so that forecasts reflect both historical patterns and known upcoming deals."*
+- *"As a Warehouse Supervisor, I want directed putaway based on item velocity, so that fast-moving items are stored for quick pick access."*
+- *"As a Customer Service Rep, I want real-time shipment tracking status visible from the order record, so that I can answer delivery questions without contacting logistics."*
+
+## Terminology notes
+- SCM is the umbrella; MRP (production planning) and elements of ERP procurement/inventory sit inside or feed into it. Don't treat SCM and MRP as interchangeable in requirements docs — SCM is broader (includes logistics, supplier management, demand planning) while MRP is specifically the materials-planning calculation.

package/dist/skills/ethical-hacking-methodology/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: ethical-hacking-methodology
+role: Ethical Hacking Methodologist
+description: >
+  Provides the complete 5-phase ethical hacking methodology guide — reconnaissance (OSINT,
+  passive/active), scanning & enumeration, exploitation, post-exploitation & persistence,
+  and reporting & remediation. Load when the task requires a structured penetration testing
+  process, methodology guidance, or step-by-step hacking workflow definition.
+triggers:
+  ["ethical hacking", "penetration testing methodology", reconnaissance, osint,
+   "scanning and enumeration", "exploitation methodology", "post exploitation",
+   "reporting and remediation", "hacking methodology", "pentest steps",
+   "pentest methodology", "penetration testing process"]
+version: 1.0.0
+requires_tools: [read_tool, glob_tool, grep_tool, run_command_tool, write_edit_tool]
+composes_with: [pentester, advanced-pentest-lab]
+---
+
+## Role
+Owns the structured 5-phase penetration testing lifecycle — providing a repeatable,
+auditable methodology that ensures no step is skipped and every finding is traceable back
+to the phase that produced it. Acts as the process framework that the pentester and
+advanced-pentest-lab skills execute within.
+
+## Process
+1. **Reconnaissance (Phase 1)** — gather intelligence without touching the target.
+   - **Passive recon**: WHOIS, DNS enumeration, Shodan, social media, job postings,
+     certificate transparency logs (crt.sh), archived pages.
+   - **Active recon**: DNS zone transfers, subdomain enumeration (Amass), live host
+     discovery (Nmap ping sweep), technology fingerprinting (Wappalyzer, WhatWeb).
+   - **OSINT aggregation**: correlate findings into a target profile — IP ranges,
+     domain names, employee names/emails, technology stack, cloud providers.
+2. **Scanning & Enumeration (Phase 2)** — probe deeply without exploiting.
+   - **Port scanning**: full TCP/UDP sweep (Nmap -sS -sU), service version detection
+     (-sV), OS fingerprinting (-O).
+   - **Vulnerability scanning**: Nessus/OpenVAS for known CVEs, Nikto for web servers,
+     manual banner grabbing.
+   - **Service enumeration**: SMB shares (enum4linux), SNMP community strings, LDAP
+     anonymous binds, web directory brute-force (gobuster, ffuf).
+   - **Web mapping**: crawl all endpoints, parameter discovery, API endpoint enumeration.
+3. **Exploitation (Phase 3)** — gain initial access.
+   - **Prioritize**: rank vulnerabilities by exploitability × impact; attempt low-risk
+     exploits first.
+   - **Exploit selection**: Metasploit modules, public PoCs, custom scripts; always
+     validate in lab before targeting production.
+   - **Credential attacks**: password spraying (not brute-force), credential stuffing
+     with breach data, default credentials.
+   - **Web exploitation**: SQLi, XSS, CSRF, file inclusion, command injection, SSRF.
+   - **Document**: every attempt — success or failure — with timestamps and payload used.
+4. **Post-Exploitation & Persistence (Phase 4)** — maintain access and expand.
+   - **Privilege escalation**: kernel exploits, SUID/SGID misconfigurations, token
+     manipulation, UAC bypass, service permissions.
+   - **Lateral movement**: PSExec, WMI, RDP hijacking, pass-the-hash, pass-the-ticket.
+   - **Persistence**: scheduled tasks, registry Run keys, WMI event subscriptions,
+     web shells, SSH authorized_keys.
+   - **Data exfiltration simulation**: staged collection, encrypted channels, exfil
+     over DNS/HTTPS to demonstrate real business impact.
+   - **Cleanup**: remove artifacts, restore configurations, delete accounts created.
+5. **Reporting & Remediation (Phase 5)** — turn technical findings into business risk.
+   - **Executive summary**: business impact, risk rating, remediation timeline.
+   - **Technical findings**: vulnerability description, exploit steps, screenshots/
+     evidence, CVSS score, affected assets, remediation guidance.
+   - **Remediation validation**: re-test after fixes applied; confirm closure.
+   - **Lessons learned**: what worked, what was blocked, detection gaps, process
+     improvements for next engagement.
+
+## Strategies
+- Passive recon first, active recon second — tipping off the target before you
+  understand the landscape wastes opportunities and triggers alerts.
+- Scanning rate-limit to avoid DoS — `--min-rate` and `--max-retries` on Nmap;
+  aggressive scans can crash fragile services.
+- Exploit the weakest link, not the most interesting one — a misconfigured SMB share
+  is a faster path to Domain Admin than a zero-day in a web app.
+- During post-exploitation, move laterally in a realistic attack path, not just
+  "everywhere possible" — demonstrate the business impact of each pivot.
+- Report findings as the business sees them: "Attacker can exfiltrate customer PII"
+  means more than "SQL injection in parameter 'id'."
+
+## Planning Approach
+- Before starting: define Rules of Engagement — scope, authorized techniques,
+  out-of-bounds systems, emergency contacts, testing window.
+- During testing: maintain an activity log with timestamps for every action;
+  this is both an audit requirement and a safety net.
+- After testing: deliver a draft report within 48 hours; final report within one
+  week; schedule a readout call to walk stakeholders through findings.
+
+## Instructions for This Task Type
+- Never begin active scanning without confirmed written authorization and a defined
+  testing window.
+- During recon, use OSINT tools (theHarvester, Amass, crt.sh) that query public data
+  — never attempt to access systems without authorization.
+- For vulnerability scanning, always configure safe checks (no dangerous plugins)
+  unless destructive testing is explicitly authorized.
+- Exploitation must target only in-scope systems; if you accidentally access an
+  out-of-scope system, stop immediately and report it.
+- Clean up all artifacts created during post-exploitation — accounts, backdoors,
+  files, scheduled tasks — before the engagement closes.
+
+## Experience / Common Pitfalls
+- Skipping passive recon and going straight to active scanning is the #1 methodology
+  failure — you miss shadow IT, acquisitions, and cloud assets invisible from the
+  primary domain.
+- Vulnerability scanners produce false positives; always manually validate before
+  reporting a finding — a scanner flag is not a confirmed vulnerability.
+- Post-exploitation cleanup failures are the most common cause of post-engagement
+  incidents — maintain a cleanup checklist and verify each item.
+- Reports that list 200 low-severity findings but miss the one critical misconfiguration
+  lose client trust — prioritize by business impact, not volume.
+- Not re-testing after remediation leaves the client with a false sense of security —
+  validation is part of the methodology, not an optional extra.
+
+## Output Artifacts
+- Rules of Engagement document
+- Reconnaissance report (target profile, OSINT findings)
+- Vulnerability inventory (ranked by CVSS × exploitability × business impact)
+- Exploitation log (timestamped, with payloads and outcomes)
+- Post-exploitation activity log and cleanup verification
+- Final penetration test report (executive summary, technical findings, remediation)
+- Remediation validation report (re-test results)

package/dist/skills/externalSkillLoader.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Returns true when XCODER_EXTERNAL_SKILLS is one of 'true', '1', or 'yes'
+ * (case-insensitive), false otherwise.
+ */
+export declare function isExternalSkillsEnabled(): boolean;
+/**
+ * Load all external skills (from <skillsDir>/<name>/SKILL.md) as formatted
+ * header strings suitable for prompt injection. Cached per resolved skills
+ * directory so each CLI run scans once per root.
+ *
+ * Returns [] when the flag is OFF, the skills directory is missing, or no
+ * valid SKILL.md files exist.
+ *
+ * Format per skill: "<SkillHeader.name>: <SkillHeader.description>"
+ * Only name + description — NOT the full body — to stay within token budget.
+ */
+export declare function getExternalSkills(opts?: {
+    skillDir?: string;
+}): string[];
+/**
+ * Clear the internal caches so the next call to getExternalSkills() or
+ * isExternalSkillsEnabled() re-reads the flag and re-loads headers.
+ * Intended for testing.
+ */
+export declare function resetExternalSkillCache(): void;

package/dist/skills/externalSkillLoader.js

@@ -0,0 +1,65 @@
+// xcoder:version 2 | xcoder:task task-f9cf18 | xcoder:updated 2026-11-02T16:14:48.582Z | xcoder:subtask code-st-077ea2
+import { SkillRegistry } from "./externalSkillRegistry.js";
+// Per-root cache: a Map keyed by the resolved skills directory, so a caller
+// that injects a different skillDir can never be served a stale result. A
+// single module-level value used to mean the first caller won for the whole
+// process lifetime.
+let cachedSkillsByRoot = new Map();
+let cachedFlag = null;
+/**
+ * Returns true when XCODER_EXTERNAL_SKILLS is one of 'true', '1', or 'yes'
+ * (case-insensitive), false otherwise.
+ */
+export function isExternalSkillsEnabled() {
+    if (cachedFlag !== null)
+        return cachedFlag;
+    const raw = process.env["XCODER_EXTERNAL_SKILLS"]?.trim().toLowerCase() ?? "";
+    cachedFlag = raw === "true" || raw === "1" || raw === "yes";
+    return cachedFlag;
+}
+/**
+ * Load all external skills (from <skillsDir>/<name>/SKILL.md) as formatted
+ * header strings suitable for prompt injection. Cached per resolved skills
+ * directory so each CLI run scans once per root.
+ *
+ * Returns [] when the flag is OFF, the skills directory is missing, or no
+ * valid SKILL.md files exist.
+ *
+ * Format per skill: "<SkillHeader.name>: <SkillHeader.description>"
+ * Only name + description — NOT the full body — to stay within token budget.
+ */
+export function getExternalSkills(opts) {
+    if (!isExternalSkillsEnabled())
+        return [];
+    // Key on the option actually passed in — NOT on the resolved default — so
+    // the SkillRegistry constructor still receives exactly what the caller gave
+    // (undefined when they gave nothing).
+    const cacheKey = opts?.skillDir ? `dir:${opts.skillDir}` : "default";
+    const cached = cachedSkillsByRoot.get(cacheKey);
+    if (cached !== undefined)
+        return cached;
+    try {
+        const registry = new SkillRegistry(opts?.skillDir);
+        const headers = registry.loadHeaders();
+        if (headers.length === 0) {
+            cachedSkillsByRoot.set(cacheKey, []);
+            return [];
+        }
+        const formatted = headers.map((h) => `${h.name}: ${h.description}`);
+        cachedSkillsByRoot.set(cacheKey, formatted);
+        return formatted;
+    }
+    catch {
+        cachedSkillsByRoot.set(cacheKey, []);
+        return [];
+    }
+}
+/**
+ * Clear the internal caches so the next call to getExternalSkills() or
+ * isExternalSkillsEnabled() re-reads the flag and re-loads headers.
+ * Intended for testing.
+ */
+export function resetExternalSkillCache() {
+    cachedSkillsByRoot = new Map();
+    cachedFlag = null;
+}

package/dist/skills/externalSkillRegistry.d.ts

@@ -0,0 +1,33 @@
+import { LoadedSkill, SkillHeader } from "../types.js";
+/**
+ * Registration manager for the Special Evolution skill system.
+ * Reads every <skillsDir>/<name>/SKILL.md, parses its YAML header so the
+ * LLM/orchestrator knows what each skill is for without loading the full body,
+ * and lazily loads the full body only when a skill is actually selected.
+ *
+ * Discovery goes through `resolveSkillsRoot()` — the single source of truth —
+ * so this class no longer joins `"skills"` onto anything itself.
+ */
+export declare class SkillRegistry {
+    private headers;
+    private paths;
+    private skillDir;
+    /**
+     * @param skillDir Explicit skills directory. When omitted (or empty) the
+     *   resolved root's skills directory is used. An explicit directory is
+     *   honoured even when it is empty — it never falls back to the bundled
+     *   packs, so tests and embedded callers get exactly the set they asked for.
+     */
+    constructor(skillDir?: string);
+    /** Scan and parse headers only — cheap, safe to call often (e.g. on --index). */
+    loadHeaders(): SkillHeader[];
+    /** Load the full skill (header + body) by name, for injection into the LLM context. */
+    loadSkill(name: string): LoadedSkill | undefined;
+    /**
+     * Route a task description to candidate skills by trigger-keyword match.
+     * Returns skills ranked by match count, highest first. Multiple skills may
+     * be selected — xcoder composes them (see composes_with in each header).
+     */
+    route(taskDescription: string): SkillHeader[];
+    list(): SkillHeader[];
+}

package/dist/skills/externalSkillRegistry.js

@@ -0,0 +1,94 @@
+// xcoder:version 1 | xcoder:task task-f9cf18 | xcoder:updated 2026-11-02T16:14:42.147Z | xcoder:subtask code-st-077ea2
+import fs from "node:fs";
+import path from "node:path";
+import { resolveSkillsRoot } from "./skills-root.js";
+import { MAX_PACK_DIRS, resolveSkillDir } from "./skill-path-guard.js";
+import { parseSkillHeaderFile } from "./skill-header.js";
+/**
+ * Registration manager for the Special Evolution skill system.
+ * Reads every <skillsDir>/<name>/SKILL.md, parses its YAML header so the
+ * LLM/orchestrator knows what each skill is for without loading the full body,
+ * and lazily loads the full body only when a skill is actually selected.
+ *
+ * Discovery goes through `resolveSkillsRoot()` — the single source of truth —
+ * so this class no longer joins `"skills"` onto anything itself.
+ */
+export class SkillRegistry {
+    headers = new Map();
+    paths = new Map();
+    skillDir;
+    /**
+     * @param skillDir Explicit skills directory. When omitted (or empty) the
+     *   resolved root's skills directory is used. An explicit directory is
+     *   honoured even when it is empty — it never falls back to the bundled
+     *   packs, so tests and embedded callers get exactly the set they asked for.
+     */
+    constructor(skillDir) {
+        this.skillDir = skillDir ? path.resolve(skillDir) : resolveSkillsRoot().skillsDir;
+    }
+    /** Scan and parse headers only — cheap, safe to call often (e.g. on --index). */
+    loadHeaders() {
+        this.headers.clear();
+        this.paths.clear();
+        let entries;
+        try {
+            entries = fs.readdirSync(this.skillDir, { withFileTypes: true });
+        }
+        catch {
+            return [];
+        }
+        let visited = 0;
+        for (const entry of entries) {
+            if (visited >= MAX_PACK_DIRS)
+                break;
+            if (!entry.isDirectory())
+                continue;
+            visited++;
+            // Validate the name and prove containment BEFORE joining anything.
+            const packDir = resolveSkillDir(this.skillDir, entry.name);
+            if (!packDir)
+                continue;
+            const skillPath = path.join(packDir, "SKILL.md");
+            const parsed = parseSkillHeaderFile(skillPath);
+            if (!parsed.ok || !parsed.header)
+                continue;
+            // Last pack wins on a duplicate name, matching the previous Map.set order.
+            this.headers.set(parsed.header.name, parsed.header);
+            this.paths.set(parsed.header.name, skillPath);
+        }
+        return [...this.headers.values()];
+    }
+    /** Load the full skill (header + body) by name, for injection into the LLM context. */
+    loadSkill(name) {
+        const skillPath = this.paths.get(name);
+        if (!skillPath)
+            return undefined;
+        const parsed = parseSkillHeaderFile(skillPath, { withBody: true });
+        if (!parsed.ok || !parsed.header)
+            return undefined;
+        return { header: parsed.header, body: parsed.body ?? "", path: skillPath };
+    }
+    /**
+     * Route a task description to candidate skills by trigger-keyword match.
+     * Returns skills ranked by match count, highest first. Multiple skills may
+     * be selected — xcoder composes them (see composes_with in each header).
+     */
+    route(taskDescription) {
+        if (this.headers.size === 0)
+            this.loadHeaders();
+        const text = taskDescription.toLowerCase();
+        const scored = [...this.headers.values()].map((h) => {
+            const score = h.triggers.reduce((acc, t) => acc + (text.includes(t.toLowerCase()) ? 1 : 0), 0);
+            return { header: h, score };
+        });
+        return scored
+            .filter((s) => s.score > 0)
+            .sort((a, b) => b.score - a.score)
+            .map((s) => s.header);
+    }
+    list() {
+        if (this.headers.size === 0)
+            this.loadHeaders();
+        return [...this.headers.values()];
+    }
+}

package/dist/skills/filesystem-management/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: filesystem-management
+role: Filesystem/Workspace Manager
+description: >
+  Manages the agent's view of the workspace filesystem — indexing, ignore rules, safe
+  read/write/move/delete operations, and keeping .agent/index in sync with reality. Load
+  whenever the task involves scanning, organizing, cleaning, moving, or indexing files/folders,
+  or when other skills need a fresh index before they can trust file state.
+triggers: [index, filesystem, "clean up files", organize, move files, delete files, workspace, ".agentignore", scan directory]
+version: 1.0
+requires_tools: [glob_tool, grep_tool, read_tool, write_edit_tool, run_command_tool, indexing_tool]
+composes_with: [programmer, architect, devops, analyst]
+---
+
+## Role
+Owns the accuracy of the agent's picture of "what's on disk" and performs filesystem
+operations safely — indexing, ignore-rule resolution, and structural changes (move/rename/
+delete) without corrupting workspace state.
+
+## Process
+1. **Resolve ignore rules** — merge .agent/.agentignore with existing .gitignore /
+   .dockerignore before any scan; never index or touch ignored paths.
+2. **Scan** — walk the workspace recursively (respecting ignores) and diff against the last
+   known index.json to find added/removed/changed files.
+3. **Index** — write/update .agent/index/index.json (filename, filepath, version, dump file,
+   start/end line) and .agent/index/index00x.dump (chunked, <500KB each).
+4. **Mutate safely** — for move/rename/delete requests: confirm the operation plan, check for
+   references via grep before deleting anything code refers to, then execute.
+5. **Re-index after mutation** — any write/edit/move/delete invalidates the affected index
+   entries; refresh them, don't leave the index stale.
+
+## Strategies
+- Treat index.json as a cache, not a source of truth — always re-verify against disk before
+  a destructive operation.
+- Chunk dump files strictly under 500KB; roll to a new index00x.dump rather than exceeding it.
+- Never delete without first grepping for references across the workspace.
+- Prefer additive/renaming operations that are reversible over hard deletes where feasible.
+
+## Planning Approach
+- Batch related filesystem changes into a single reviewable plan before executing, rather
+  than mutating file-by-file with no overview.
+- For large reorganizations, produce a move-map (old path → new path) as an artifact before
+  touching anything.
+
+## Instructions for This Task Type
+- Always resolve .agentignore + .gitignore + .dockerignore before scanning or indexing.
+- Never exceed 500KB per dump file; split and update index.json's file→dump mapping.
+- Surface a dry-run plan for any multi-file move/delete before executing if the change is
+  non-trivial (more than a few files).
+
+## Experience / Common Pitfalls
+- Stale indexes are worse than no index — a skill trusting a stale index.json will act on
+  wrong file locations/content.
+- Ignoring .gitignore rules leads to indexing build artifacts/dependencies, bloating dump
+  files and wasting LLM context.
+- Deleting a file still referenced elsewhere is the most common destructive-operation mistake.
+
+## Output Artifacts
+- .agent/index/index.json
+- .agent/index/index00x.dump
+- move-map / change plan (for reorganizations)

package/dist/skills/first-run-seed.d.ts

@@ -0,0 +1,26 @@
+/**
+ * First-run seeding: copy the shipped packs into ~/.xcoder/skills once the CLI
+ * actually starts, so a user gets an editable, uninstall-surviving tree.
+ *
+ * This is strictly best-effort. Seeding runs at most once per process, never
+ * throws, and never touches files it does not own (see seed-skills.ts).
+ */
+import { getUserHomeSkillsDir } from "./skills-root.js";
+/**
+ * Seed ~/.xcoder/skills from the shipped packs, once per process.
+ *
+ * Returns the seed summary for tests, or `undefined` when there was nothing
+ * to do, it was already attempted, or it failed — failures are swallowed so a
+ * read-only home directory can never stop the CLI from starting.
+ */
+export declare function maybeSeedSkillsHome(opts?: {
+    sourceDir?: string;
+    homeDir?: string;
+}): Promise<{
+    written: number;
+    updated: number;
+    preserved: number;
+} | undefined>;
+/** Test hook: allow another seed attempt in the same process. */
+export declare function resetFirstRunSeedState(): void;
+export { getUserHomeSkillsDir };

package/dist/skills/first-run-seed.js

@@ -0,0 +1,75 @@
+// xcoder:version 2 | xcoder:task task-f9cf18 | xcoder:updated 2026-11-02T16:15:56.920Z | xcoder:subtask code-st-077ea2
+/**
+ * First-run seeding: copy the shipped packs into ~/.xcoder/skills once the CLI
+ * actually starts, so a user gets an editable, uninstall-surviving tree.
+ *
+ * This is strictly best-effort. Seeding runs at most once per process, never
+ * throws, and never touches files it does not own (see seed-skills.ts).
+ */
+import os from "node:os";
+import path from "node:path";
+import { log } from "../util/logger.js";
+import { getAppDir, getUserHomeSkillsDir, probeSkillsDir } from "./skills-root.js";
+import { seedSkillsHome } from "./seed-skills.js";
+let attempted = false;
+/**
+ * Candidate locations for the SHIPPED packs (never the user's home copy).
+ * Order mirrors resolveSkillsRoot's installer candidates.
+ */
+function bundledSkillsCandidates() {
+    const appDir = getAppDir();
+    const exeDir = path.dirname(process.execPath);
+    return [
+        path.join(appDir, "skills"),
+        path.join(exeDir, "..", "share", "xcoder", "skills"),
+        path.join(appDir, "..", "skills"),
+        path.join(appDir, "..", "..", "skills"),
+        path.join(process.cwd(), "skills"),
+    ];
+}
+function findBundledSkillsDir() {
+    for (const candidate of bundledSkillsCandidates()) {
+        if (probeSkillsDir(candidate).count > 0)
+            return candidate;
+    }
+    return undefined;
+}
+/**
+ * Seed ~/.xcoder/skills from the shipped packs, once per process.
+ *
+ * Returns the seed summary for tests, or `undefined` when there was nothing
+ * to do, it was already attempted, or it failed — failures are swallowed so a
+ * read-only home directory can never stop the CLI from starting.
+ */
+export async function maybeSeedSkillsHome(opts) {
+    if (attempted)
+        return undefined;
+    attempted = true;
+    if (process.env["XCODER_SKIP_SKILLS_SEED"] === "1")
+        return undefined;
+    const sourceDir = opts?.sourceDir ?? findBundledSkillsDir();
+    if (!sourceDir)
+        return undefined;
+    const homeDir = opts?.homeDir ?? os.homedir();
+    try {
+        const result = await seedSkillsHome({ sourceDir, homeDir });
+        if (process.env["XCODER_DEBUG_CONFIG_PATH"] && result.action !== "unchanged") {
+            log.dim(`skillsSeed: ${result.action} (written=${result.written.length}, ` +
+                `updated=${result.updated.length}, preserved=${result.preserved.length})`);
+        }
+        return {
+            written: result.written.length,
+            updated: result.updated.length,
+            preserved: result.preserved.length,
+        };
+    }
+    catch {
+        // Never let seeding break startup.
+        return undefined;
+    }
+}
+/** Test hook: allow another seed attempt in the same process. */
+export function resetFirstRunSeedState() {
+    attempted = false;
+}
+export { getUserHomeSkillsDir };