Engineering Discipline for Autonomous Agents.
AI can generate code. The harder problem is making it operate within explicit boundaries, verify its assumptions, and know when it should stop.
Craftsman is an open-source engineering skill system for coding agents, built around explicit scope, architectural boundaries, verification, and failure-aware execution.
Code generation is becoming cheap.
Correct integration is not.
An autonomous coding agent can generate hundreds of lines of syntactically valid code in seconds. Without explicit guidance, it can just as quickly break database transaction isolation, alter state ownership across component boundaries, introduce subtle authorization bypasses, or expand the scope of a task with unrequested abstractions.
Speed without constraints accelerates architectural decay. Engineering correctness requires operational context: scope budgets, system boundaries, business invariants, schema integrity, security defenses, and empirical verification.
Craftsman puts those engineering constraints directly into reusable agent context, forcing agents to operate under the same rigor expected of an experienced software engineer.
Craftsman
Craftsman is an open-source suite of 14 canonical skill directories and a zero-dependency POSIX installation engine. It provides platform-agnostic, constitutional rules that govern how AI coding agents write, refactor, and verify code.
npx skills add godamri/craftsmanInstalls directly into detected agent environments via the open agent skills protocol.
./install.sh --ide allDeploys local symlinks and configures Claude, Cline, Cursor, Copilot, Windsurf, and AGENTS.md.
Core Execution & Scope
Practical engineering execution guidance focused on milestone-based delivery, repository reconnaissance, vertical-slice implementation, behavioral boundary verification, falsification, and regression control.
Practical operational discipline for coding agents to identify and communicate the smallest justified change before implementation. Prevents architecture hallucination, redundant abstractions, duplicate systems, and silent scope expansion.
Practical system architecture guidance focused on system boundaries, state ownership, dependency direction, failure domain isolation, and evolutionary design.
Practical software engineering guidance focused on requirements validation, domain modeling, transaction boundaries, failure handling, security invariants, testing, and release gates.
Systems & Architecture
Practical database engineering guidance focused on schema integrity, transaction correctness, concurrency control, safe migrations, and query performance.
Practical distributed systems guidance focused on state consistency, idempotency, message delivery semantics, fencing tokens, outbox patterns, and resilient recovery.
Practical security engineering guidance focused on threat modeling, fail-closed authorization, input sanitization, secret management, injection defense, and auditability.
Delivery, Quality & Governance
Practical infrastructure and SRE guidance focused on server administration, credential security, safe database operations, failure recovery, and zero-downtime changes.
Practical quality assurance guidance focused on risk-based testing, invariant assertions, concurrency verification, failure injection, and deterministic release gates.
Practical business and product guidance focused on value validation, portfolio prioritization, risk containment, delivery readiness, and outcome realization.
Language Crafts
Practical Go engineering guidance (Go 1.22+) focused on correctness, explicit error handling, structured concurrency, memory ownership, and test verification.
Practical Rust systems engineering guidance (Rust 2021/2024) focused on memory safety, sound ownership, explicit error propagation, async Tokio task lifecycles, and verification gates.
Practical Python engineering guidance (Python 3.12+) focused on simple sufficient design, explicit failure semantics, data modeling, safe concurrency, and measurable performance.
Practical React and modern web guidance focused on derived state, resilient asynchronous lifecycles, accessible UI, and empirical performance profiling.
The Craftsman Loop
An agent should not simply produce code and stop. It must operate inside an explicit execution and verification loop that prioritizes observable evidence over code volume.
Supreme Axiom: An implementation is not complete when the code exists. It is complete when intended behavior is demonstrated across its execution boundary and relevant failure modes have been tested.
Identify objective, constraints, and scope boundaries.
Inspect existing patterns, canonical implementations, and lifecycles.
Define independent vertical slices with strict change budgets.
Document observable input, state, and output acceptance criteria.
Write the minimum code required for the current vertical slice.
Execute behavioral boundary verification across the component surface.
Actively attack assumptions under edge cases and failure modes.
Form root-cause hypotheses and apply surgical fixes. No blind patching.
Re-run failed verification scenarios to prove defect elimination.
Run blast-radius regression across callers and prior milestones.
Anti-overengineering stop rule: close when exit criteria pass.
Document verified behavior, audit evidence, and advance.
One Source. Many Agent Environments.
Instead of duplicating skill definitions across IDE formats, Craftsman maintains a single canonical source of truth under .agents/skills/. Target environments consume projections: native symlink adapters for platforms with dedicated skill folders, or delimited rule bridges for instruction-driven editors.
Craftsman
Canonical Skills
│
┌────────────┼────────────┐
│ │ │
Native Rule Agent
Adapters Bridges Context
│ │ │
Claude Cursor AGENTS.md
Cline Copilot
WindsurfEngineering Principles
No trust by default. No authority by implication.
Business Correctness
Value validation before complexity. Reject ungrounded abstractions that do not directly fulfill specified requirements.
Data Integrity & Concurrency
Enforce strict schema constraints, transaction isolation boundaries, locking discipline, and safe non-blocking migrations.
Security & Authorization
Fail-closed authorization, strict input sanitization, secret isolation, SSRF prevention, and auditable telemetry.
State Ownership & Reliability
Clear single-writer state ownership, explicit failure domains, idempotency guarantees, and resilient recovery paths.
Controlled Change
The smallest justified change. Strict change budgets with zero speculative architecture or duplicate subsystems.
Failure-Path Testing
Explicit verification of disconnections, timeouts, race conditions, corrupted inputs, and recovery lifecycles.
Verification Before Confidence
Implemented ≠ Verified ≠ Validated ≠ Production Ready. Evidence of working behavior takes precedence over code presence.
Explicit System Boundaries
Clean dependency directions, decoupled interfaces, and strict encapsulation between subsystems and integration layers.
What It Is Not
Craftsman establishes explicit engineering constraints. To remain effective and lightweight, it deliberately limits its scope:
Not a prompt library
Does not contain conversational templates or ad-hoc tips. Every skill defines strict constitutional constraints and failure modes.
Not a deployment daemon
No background processes, background telemetry, or automated push services. Operates entirely inside the developer's local environment.
Not an engineering replacement
Does not replace human judgment, threat modeling, or architectural sign-off. It equips the agent to respect those boundaries.
Not an invasive framework
Does not require proprietary runtimes or changes to application code. It integrates cleanly through native markdown and relative symlinks.
Not a productivity gimmick
Makes no claims of "10x speed". Its goal is reducing defect rates, containing regression blast radius, and preventing architectural drift.
Built, Not Claimed.
The installation and verification engine is verified through hostile automated test batteries before every release:
Exact Tree Topology Verification
The copy verifier compares full directory hierarchies, entry types (files, directories, symlinks, special files), and runs byte-for-byte cmp -s on all regular content before authorizing replacement.
Path Identity & Canonical Receipts
Symlinks are verified using physical path canonicalization (cd -P) to reject substring spoofing. Copied trees require exact schema validation via .craftsman-receipt.json.
Staged Replacement & Signal Trap Cleanup
Updates are staged in isolated mktemp -d directories and verified before replacing existing files. Trap handlers clean temporary state on EXIT, INT, TERM, and HUP.
Deterministic State-Machine Parser
Rule bridges use strict boundary markers. Unclosed, nested, or duplicate marker blocks trigger immediate fail-closed aborts, preserving surrounding user configurations byte-for-byte.
Inspect the System
The implementation is public. The skills, installer, integration model, and engineering rules can be inspected directly on GitHub or installed through the open agent skills registry.
I build systems where correctness matters after the demo is over — payment flows, commerce infrastructure, distributed services, and now the tooling that governs how coding agents interact with them.
Craftsman reflects the same standard applied to financial ledgers and production backends: deterministic state, defensive boundaries, and evidence over speculation.