Architekton is a skills-first engineering-practice system for understanding how a selected repository expects work to be changed, validated, reviewed, and maintained.
The public experimental alpha remains inspect-led. architekton:inspect compiles effective repository practice without changing the inspected repository. architekton:bootstrap and architekton:maintain are guarded previews for explicitly authorized creation or maintenance of native guidance. architekton:verify independently checks a proposal or landed change without mutation.
Node.js and TypeScript power the first optional deterministic inspection adapter. They are not a restriction on which repository languages Architekton can understand. Other ecosystems begin as guidance-driven inspection and gain maintained adapters only when repeated use justifies them.
flowchart TD
Request["Maintainer request"] --> Inspect["architekton:inspect"]
Inspect --> Discovery["Safe, read-only discovery"]
Native["Native repository artifacts"] --> Discovery
Discovery --> Evidence["Evidence with scope and provenance"]
Inspect --> Questions["Focused questions for material tacit knowledge"]
Questions --> Evidence
Evidence --> Report["Effective-state report"]
Report --> States["pass · fail · unknown · stale · unsupported · conflicting"]
Report --> Decision{"Human decision"}
Decision -->|"Audit only"| Unchanged["Repository remains unchanged"]
Decision -->|"Missing guidance confirmed"| Bootstrap["architekton:bootstrap"]
Bootstrap --> Brief["Review exact ENGINEERING.md proposal"]
Brief --> Approval["Approve exact path · bytes · SHA-256"]
Approval --> Create["Exclusive create + byte verification"]
Create --> Reinspect["Read-only re-inspection"]
Reinspect --> MaintainerHandoff["Maintainer handoff"]
Decision -->|"Maintenance explicitly authorized"| Maintain["architekton:maintain"]
Maintain --> Proposal["Reviewable updates to existing guidance"]
Proposal --> ChangeApproval["Approve exact existing-file update"]
ChangeApproval --> Apply["Apply bounded update"]
Apply --> Reinspect
Reinspect --> Verify["architekton:verify"]
Decision -->|"Code/workflow/config remediation"| RemediationHandoff["Authorized coding-agent handoff"]
RemediationHandoff --> Verify
Verify --> HandoffResult["Independent verdict + exact next actions"]
Native files remain authoritative for the facts they directly express. Architekton compiles an explainable view across them, asks when important intent is missing, and never lets repository content authorize its own mutation.
Architekton defines coverage by evidence mechanism and the selected repository root, not by claiming complete understanding of a repository type.
| Repository shape | First public alpha coverage |
|---|---|
| Skills and documentation repository | Guided inspection of native guidance, manifests, ownership, and workflows; no claim that skill behavior is correct |
| Root JavaScript/TypeScript package | Guided inspection plus deterministic root package, lockfile, script-name, guidance, ownership, and workflow evidence |
| Nested or hybrid repository | Guided inspection within the selected root; nested allowlisted artifacts are inventoried |
| Nested JavaScript package | May be selected explicitly as the repository root for deterministic root-package inspection |
| JavaScript/TypeScript monorepo | Root evidence is supported; workspace and package-to-package composition are not supported |
| Other ecosystems | Guided inspection only; no deterministic language adapter is implied |
Guided coverage is progressive and non-exhaustive: inspect the smallest relevant native evidence first, then expand only when that evidence points elsewhere. The alpha does not inspect application source code, prove that declared commands pass, evaluate framework correctness, or observe unavailable hosted settings. The report must expose those limits rather than converting them into pass or fail.
For the public alpha, architekton:inspect is the headline and default prompt. The plugin packages four skills under the architekton namespace; architekton:bootstrap and architekton:maintain are guarded write previews, while architekton:verify is read-only. Bootstrap requires at least one real maintainer-answer round and creates only a root, tool-independent ENGINEERING.md after approval of the exact path, bytes, and SHA-256. Maintenance treats existing ENGINEERING.md as first-class and synchronizes other native guidance only when explicitly scoped. Neither workflow creates AGENTS.md or CLAUDE.md.
skills/
├── inspect/
│ ├── SKILL.md
│ ├── references/
│ └── scripts/runtime/ # optional compiled Node adapter
├── bootstrap/
│ ├── SKILL.md
│ └── references/
├── maintain/
│ ├── SKILL.md
│ └── references/
└── verify/
├── SKILL.md
└── references/
Install the repository as the architekton plugin to expose architekton:inspect, architekton:bootstrap, architekton:maintain, and architekton:verify. The inspect and verify skills remain useful when Node.js is unavailable; the host agent falls back to safe, read-only file inspection.
The repository must be accessible to the runtime. The public installation flow is:
codex plugin marketplace add pariyar07/architekton
codex plugin add architekton@architektonStart a new task, select the repository root, and ask Codex to inspect its effective engineering practice. Natural-language triggering was verified in Codex with the supported hosted model used during alpha testing. Explicit invocation also remains available as architekton:inspect.
Invoke architekton:bootstrap only when a maintainer explicitly asks to establish missing project-owned engineering guidance. It inspects first, asks one focused question at a time, and remains proposal-only until the exact root ENGINEERING.md path, bytes, and SHA-256 receive fresh approval. Its helper exclusively creates the file, writes and syncs the approved bytes, immediately re-reads it, and reports failure if the published identity or raw bytes differ. This detects interference visible during verification; it does not claim atomic publication, prevent every same-user race, or detect later changes. A racing reader could observe incomplete content during the initial write.
Invoke architekton:maintain to propose explicitly scoped updates to an existing ENGINEERING.md or other existing native guidance. It shows the exact diff before one approval of the unchanged proposal and never silently edits CI, code, configuration, or hosted controls.
Invoke architekton:verify after bootstrap, maintenance, remediation, or another proposed or landed repository-practice change. It checks the intent and diff read-only, discloses whether assessments were independent or degraded, and does not repair findings.
Remove both the plugin and its marketplace entry:
codex plugin remove architekton@architekton
codex plugin marketplace remove architektonclaude plugin marketplace add pariyar07/architekton
claude plugin install architekton@architektonStart a new session in the selected repository and invoke:
/architekton:inspect
Use /architekton:bootstrap explicitly for the guarded missing-guidance workflow. Claude Code testing requires explicit invocation and a fresh session after installing or upgrading the plugin.
Use /architekton:maintain for explicitly scoped existing-guidance updates and /architekton:verify for read-only verification of a proposal or landed change.
Natural-language triggering is not supported for Claude Code in this alpha because testing with Haiku and Sonnet did not reliably load and follow the evidence contract. Use the explicit slash invocation.
Remove both the plugin and its marketplace entry:
claude plugin uninstall architekton@architekton
claude plugin marketplace remove architektonReports preserve these outcomes independently:
passfailunknownstaleunsupportedconflicting
Requires Node.js 22 or newer.
npm install
npm test
npm run buildBuild and run the current adapter:
node skills/inspect/scripts/runtime/cli.js inspect /absolute/path/to/repositoryThe alpha adapter writes JSON only to standard output. It does not accept an output pathname; callers that need persistence must choose and control that destination outside Architekton. Its GitHub Actions checks recognize bounded static patterns such as overlapping triggers, notification error masking, conditional/path-filter risk, docs fast paths, runtime drift, and Dependabot target branches. They do not execute YAML, inspect hosted rules, or prove behavioral outcomes.
The adapter's report contract and JavaScript package-manager coverage are experimental. They do not define the language-neutral skill contract.
- ENGINEERING.md records the accepted alpha engineering intent.
- AGENTS.md gives coding-agent instructions for developing Architekton itself.
- CLAUDE.md imports those instructions for Claude Code contributors to this repository.
These repository files are not templates for inspected projects. Architekton never creates AGENTS.md or CLAUDE.md. The bootstrap preview can create only a root ENGINEERING.md through its exact-approval helper; architekton:maintain only updates an existing file when explicitly requested.
Architekton is a public experimental alpha. Apache-2.0, DCO contribution terms, support and security expectations, focused dogfooding, and explicit limitations remain part of its release discipline. A release announcement or launch blog follows separate owner approval so every claim can point to inspectable evidence.
See CONTRIBUTING.md, SECURITY.md, CODE_OF_CONDUCT.md, and SUPPORT.md before participating in the alpha.