Runtime layers

• CLI Shell (`achilles-cli.mjs`): parses commands, manages history, prompts, cancellation, and interactive loop.
• Planning & Execution (`planService`, `intentionToSkill`, `executionHelpers`): builds LLM plans, executes skills, resumes or cancels.
• Skill Runtime (`RecursiveSkilledAgent` from achillesAgentLib): registers local skills, resolves orchestrators, runs with review mode.
• Memory (`MemoryManager`): global/user/session memories, routed by LLM into `.history_*` snapshots.
• Specs Workspace (`GampRSP`): creates `.specs`, manages URS/FS/NFS/DS files, traceability, HTML docs.
• Bootstrap (`bootstrapHelpers`): auto-runs default steps (e.g., ignore-files) and caches completion.

Data directories

• .specs/: URS.md, FS.md, NFS.md, DS/*, .ignore, .llm_logs, .llm_stats, html_docs/.
• docs/specs/: Published specification set (this documentation) with DS-per-file mirror.
• docs/architecture/: HTML narratives of runtime layers and flows.

Key flows

1. Bootstrap: detect `.specs`; if missing, create URS/FS/NFS skeletons, DS/, ignore list.
2. Task intake: user enters free text or commands; LLM planner emits skill steps; user may confirm.
3. Execution: skills run with context (workspace, specsRoot, memories, language contract); actions update specs.
4. Memory & Resume: summaries routed to global/user/session; pending plans persisted in-process for /resume.
5. Spec publishing: `GampRSP.generateHtmlDocs()` renders html_docs for browsing; docs/specs mirrored for static docs.

LLM & skills

AchillesCLI wraps LLMAgent (fast/deep modes, cancellation, debug logging) and executes local skills discovered under .AchillesSkills (workspace or CLI bundle). The planner prefers orchestrator skills for high-level tasks and warns when none exist.

Installed skills (type: oskill¹)

• update-specs — plans and applies URS/FS/NFS/DS/test/file-impact actions from change requests.
• build-code — regenerates files from DS File Impact blocks and scaffolds FS/NFS test suites.
• sync-specs — scans code and drafts specs/DS/file-impact to sync undocumented files.
• ignore-files — maintains the .specs/.ignore list of skipped paths.
• generate-docs — rebuilds static HTML docs from the current specs set.
• fix-tests-and-code — iterates run-tests + build-code to repair failing suites and code.
• run-tests — executes runAlltests.js (optionally scoped to a suite) and returns results.
• spec-review — LLM review of specs with structured findings and recommendations.
• refactor-design — captures refactor intents into DS updates and triggers build-code.
• generic-skill — fallback tool runner (list/read/rewrite/replace/create/delete files) when no specific skill fits.
• spec-mentor — educational guidance on URS/FS/NFS/DS/tests with suggested next steps.
• generate-summary — non-mutating spec summary for quick overviews (no HTML docs regeneration).
• spec-help — concise refresher on the GAMP spec stack and best practices.
• specPlanner (utility) — shared planner/executor for spec skills (parses plans, applies GampRSP actions).

¹oskill: orchestrator-type skill that plans and coordinates other skills; it does not answer the prompt directly.

Execution in practice (iterative spec cycle)

You can compose the existing skills to build and refine specs end-to-end, including backtracking:

1. Draft specs: run update-specs with your change request to create/adjust URS/FS/NFS/DS and file impacts.
2. Preview: use generate-summary to generate a non-mutating summary and inspect the changes.
3. Regenerate code/tests: if the DS looks good, run build-code to materialize files and scaffold FS/NFS test suites.
4. Backtrack/refine: if the preview or generated files aren’t what you want, run sync-specs to re-sync specs from code or rerun update-specs with revised instructions (e.g., new constraints or different file impacts).
5. Repair loops: if tests/code drift, use fix-tests-and-code to iterate run-tests + build-code until stabilized.
6. Review and mentor: call spec-review for findings and spec-mentor for educational guidance before finalizing.
7. Publish: regenerate docs with generate-docs to update HTML outputs, or run-tests to validate suites.