4.7 KiB
SKILL: Engineering Standards (Universal Literate Note)
- Overview
- The Mandates (Operational Standards)
- Phase B: Blueprint (PROTOCOL)
- Phase D: Build (Implementation)
- See Also
Overview
These are the strict Engineering Standards for all development within this system. They ensure that every line of code is provably correct, auditable, and maintainable. These standards are enforced both through the agent's instructions and physical Lisp safety gates.
The Mandates (Operational Standards)
1. Commit Before Modify
You MUST commit and push the current state of the workspace BEFORE initiating any new file modifications. This ensures a clean recovery point. The system physically blocks file modifications if the working tree is dirty.
2. Literate Programming (The Single Source of Truth)
All system logic and skills MUST be implemented as Literate Org files. Weaving documentation and code together ensures that the "Why" (Architectural Intent) is never separated from the "How" (Implementation).
3. Literate Granularity
Every Lisp function, macro, or variable must reside in its own dedicated `#+begin_src lisp` block. This allows for specific narrative explanation for every logical unit.
4. Test-Driven Development (Continuous QA)
No change is complete without verification. Every new function or macro must be accompanied by a FiveAM test case. You must run the test suite and verify success before considering a task complete.
5. The Consensus Loop (Plan Mode)
Major architectural shifts or complex refactors require a formal implementation plan. You must enter Plan Mode, draft a Blueprint (PROTOCOL), and seek formal approval before execution.
6. The Stop-and-Wait Mandate (Turn-Yielding)
You are strictly forbidden from drafting a plan or requesting formal approval in the same conversational turn that you propose an initial strategy or begin file discovery. You MUST propose your strategy in plain text, explicitly state "Waiting for user feedback," and yield the turn. You may only proceed to draft the `.md` plan after the user explicitly replies with agreement.
7. GTD Synchronization (Roadmap Integrity)
You are strictly forbidden from considering a task complete without updating `gtd.org`. Every major architectural shift, feature implementation, or refactor MUST be recorded in the project roadmap to ensure technical transparency and historical auditability.
Phase B: Blueprint (PROTOCOL)
1. Architectural Intent
The Engineering Standards skill provides the deterministic enforcement of the workflow. It intercepts agent actions and validates them against the git environment and system state.
2. Semantic Interfaces
`verify-git-clean-p`
- Purpose: Checks if the git repository is in a clean state.
- Returns: `t` if clean, `nil` if dirty.
Phase D: Build (Implementation)
Git Status Enforcement
(in-package :org-agent)
(defun verify-git-clean-p (dir)
"Returns T if the git repository at DIR has no uncommitted changes."
(let ((status (uiop:run-program (list "git" "-C" (namestring dir) "status" "--porcelain")
:output :string
:ignore-error-status t)))
(string= "" (string-trim '(#\Space #\Newline #\Tab) status))))
(defun engineering-standards-gate (action context)
"Physically enforces the 'Commit Before Modify' rule."
(let* ((payload (getf action :payload))
(act (or (getf payload :action) (getf action :action)))
(target-file (getf payload :file)))
;; If the action involves modifying files, check git status
(when (member act '(:modify-file :write-file :replace :rename-file :delete-file))
(let ((proj-root (asdf:system-source-directory :org-agent)))
(unless (verify-git-clean-p proj-root)
(harness-log "DETERMINISTIC [Standards]: BLOCKING ACTION. Working tree is dirty. Commit changes before modification.")
(return-from engineering-standards-gate
(list :type :LOG :payload (list :text "Engineering Standard Violation: Working tree dirty. You MUST commit before modifying files."))))))
action))Skill Definition
(org-agent:defskill :skill-engineering-standards
:priority 900 ; High priority, runs before most skills
:trigger (lambda (ctx) t) ; Always active
:probabilistic nil
:deterministic #'engineering-standards-gate)