org-agent-contrib/org-skill-project-foundry.org

:PROPERTIES:
:ID:       37f2b59f-4537-4cca-ac7f-5c24b9e2e773
:CREATED:  [2026-03-30 Mon 21:16]
:EDITED:   [2026-04-08 Wed 10:45]
:END:
#+TITLE: SKILL: Project Foundry Agent (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :foundry:scaffolding:system:psf:lisp:engineering:

* Overview
The *Personal Software Foundry (PSF)* is a highly integrated, neurosymbolic "virtual software house" embedded within the Memex. It is the overarching system used to design, implement, and maintain all software projects. The PSF ensures that every line of code is provably correct, secure, and part of a self-improving cognitive loop.

The *Project Foundry Agent* is the specific skill responsible for the physical instantiation of these new projects. It automates directory creation, version control initialization, and GTD integration, ensuring every new project adheres to PSF mandates.

* The PSF Mandates (Philosophy & Policy)
All software developed within the Foundry must adhere to these foundational principles:

** 1. Lisp Machine Sovereignty
The agent is a Lisp Machine image (SBCL). The system is a "Living Organism" where code is updated via hot-reloading into the active image. Manual "Restarts" are considered a failure of the late-binding architecture.

** 2. Homoiconic Memory (The Org Mandate)
Every document, plan, PRD, and skill in the system MUST be written in Org-mode (.org). Markdown (.md) and JSON/YAML/XML are strictly prohibited for internal system logic and institutional memory. Org-mode provides a rigorous, hierarchical AST for both humans and machines.

** 3. Literate Programming (The Knuth-Sovereign Principle)
The PSF treats code not as a series of instructions for a computer, but as a "work of literature" for humans that happens to be executable. 
- *Implementation:* All `org-agent` skills and system logic MUST be implemented as Literate Org files using `#+begin_src` blocks. 
- *Rationale:* By weaving documentation and code together, we ensure that the "Why" (Architectural Intent) is never separated from the "How" (Implementation). This is the key to the PSF's *Institutional Memory*.

** 4. Hardware Compartmentalization
The runtime environment is an enclosure (Docker, LXC, VM, or Bare Metal). The PSF kernel remains agnostic to its enclosure.

** 5. Educational & Sovereign Interaction
The Foundry serves as a mentorship environment. Agents must explain the "Why" and distill knowledge to increase user technical mastery. The user (Sovereign Executive) retains absolute right to deep-dive into any technical layer.

** 6. Literate Granularity (One Function per Block)
To maintain the highest quality of literate programming, every Lisp function or macro must reside in its own dedicated `#+begin_src lisp` block. This ensures that each piece of logic can be surrounded by rich narrative explaining the "Why" and "How" of its specific implementation.

** 7. Commit Before Modification
To ensure perfect reversibility and system integrity, the agent MUST commit and push the current state of the workspace BEFORE initiating any new file modifications. This ensures that every evolutionary step has a known-good recovery point.

** 8. Continuous QA (Chaos & Testing)
No change is complete without verification. Every new function must be accompanied by a FiveAM test case. Furthermore, the agent must use the 'Chaos Gauntlet' to simulate failures and verify the system's resilience after every significant architectural shift.

* Architectural Foundation (CLOSOS Principles)
The PSF is built on the *Common Lisp Object-Store Operating System (CLOSOS)* specification:
- [[file:closos_attributed_object_store.org][Object-Store First]]: Data is treated as Attributed Lisp Objects (via `org-element` AST), not flat files.
- [[file:closos_single_address_space.org][Single Address Space]]: The CL Daemon and Emacs share a conceptual address space via OACP (Remote Object Proxy).
- [[file:closos_memory_persistence.org][Persistence by Default]]: The Lisp Image is persistent; state is unalterable and auditable.
- [[file:closos_multiple_environments.org][Multiple Environments]]: Isolation by scope allows for safe, simultaneous global environments.
- [[file:closos_protection_mechanisms.org][Language-Based Protection]]: Security is enforced by the compiler and runtime (tagged pointers, capabilities).

* The Foundry Workflow (The "Consensus Loop")
Projects pass through sequential "Safety Gates" managed by specialized departments:

| Phase | Department | Responsibility | Key Instrument |
| :--- | :--- | :--- | :--- |
| *A: Demand* | *Product* | User Interview & Needs | `PRD.org` |
| *B: Blueprint* | *Design* | Structural Integrity & API | [[file:../system/skills/org-skill-architect.org][Architect Skill]] |
| *C: Success* | *Quality* | TDD Inception & Security Audit | [[file:../system/skills/org-skill-tech-analyst.org][Analyst Skill]] |
| *D: Build* | *Engineering* | Minimal Implementation | `src/`, [[file:skill-project-foundry.org][Foundry Skill]] |
| *E: Chaos* | *Chaos* | Dynamic Testing & Chaos Eng. | [[file:org-skill-chaos.org][Chaos Skill]] |
| F: Memory | *Optimization* | Institutional Memory & RCA | [[file:institutional_memory.org][institutional_memory.org]], [[file:../system/skills/org-skill-scribe-rca.org][Scribe-RCA Skill]] |

** Success Matrix: "The Level 3 Standard"
A project is not complete until it achieves *Evolutionary Completion*:
1. *Functional:* Code merged and passing all audits (Chaos Gauntlet).
2. *Institutional:* Session distilled into atomic notes; code groomed for zero bloat.
3. *Evolutionary:* Automated health checks and recurring maintenance tasks established in `gtd.org` as standard task sequences.

* Operational Standards
- *Project Root:* All projects live in `memex/5_projects/`.
- *Common Structure:*
  - `README.org` (Vision)
  - `PRD.org` (Requirements)
  - `PROTOCOL.org` (Interfaces)
  - `src/` (Implementation)
  - `tests/` (Verification)
  - `docs/` (Architecture/Chaos/RCA)
- *Self-Improvement (RCA):* Every bug triggers a *Root Cause Analysis* note to update "Permanent Learnings" in `SOUL.org`.

* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:

** 1. Purpose
Define automated project instantiation behaviors for the PSF.

** 2. User Needs
- *Workspace Scaffolding:* Create standard `src/`, `tests/`, `docs/` layout and boilerplate files.
- *Version Control:* Initialize Git in new project directories.
- *GTD Integration:* Automatically append projects and initial tasks to `gtd.org`.
- *Safety:* Prevent overwriting existing projects and log all actions.

** 3. Success Criteria
*** TODO Structural Compliance
*** TODO GTD Linkage Verification
*** TODO Idempotency Check

* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: DRAFT
:END:

** 1. Architectural Intent
The Project Foundry Agent will be implemented as a command-line tool callable with a project name and optional parameters (e.g., programming language). It will leverage existing system tools (e.g., `mkdir`, `git`, `emacsclient`) to perform its tasks. Error handling and logging will be crucial. It should be idempotent, meaning that re-running the agent on the same project should not cause errors or duplication.

** 2. Semantic Interfaces (Lisp Signatures)

*** `foundry-create-project`
    - Purpose: Top-level function to create a new project.
    - Signature: `(foundry-create-project project-name &key language git gtd)`
    - Arguments:
      - `project-name`: String, the name of the project (and base directory).
      - `language`: Keyword, the programming language paradigm of the project (e.g., `:python`, `:lisp`, `:javascript`). Influences boilerplate content. Defaults to `:generic`.
      - `git`: Boolean, whether to initialize a Git repository (default: `t`).
      - `gtd`: Boolean, whether to add the project to the GTD system (default: `t`).
    - Returns: Symbol, `:success` if the project was created successfully, `:failure` otherwise.
    - Side Effects: Creates directories, files, a git repo (optionally), and modifies the GTD system (optionally).

*** `foundry-create-directories`
    - Purpose: Creates the standard project directory structure.
    - Signature: `(foundry-create-directories project-path)`
    - Arguments:
      - `project-path`: String, the absolute path to the project directory.
    - Returns: Boolean, `t` if successful, `nil` otherwise.
    - Side Effects: Creates `src`, `tests`, and `docs` directories.

*** `foundry-create-boilerplate-files`
    - Purpose: Creates boilerplate files based on the project language.
    - Signature: `(foundry-create-boilerplate-files project-path language)`
    - Arguments:
      - `project-path`: String, the absolute path to the project directory.
      - `language`: Keyword, the programming language of the project.
    - Returns: Boolean, `t` if successful, `nil` otherwise.
    - Side Effects: Creates initial files (e.g., `README.md`, `main.py`, `index.html`).

*** `foundry-initialize-git`
    - Purpose: Initializes a Git repository in the project directory.
    - Signature: `(foundry-initialize-git project-path)`
    - Arguments:
      - `project-path`: String, the absolute path to the project directory.
    - Returns: Boolean, `t` if successful, `nil` otherwise.
    - Side Effects: Executes `git init` in the project directory.

*** `foundry-add-to-gtd`
    - Purpose: Adds the project and initial tasks to the GTD system.
    - Signature: `(foundry-add-to-gtd project-name)`
    - Arguments:
      - `project-name`: String, the name of the project.
    - Returns: Boolean, `t` if successful, `nil` otherwise.
    - Side Effects: Appends to `gtd.org` using `emacsclient`.

* See Also
- [[file:../projects/org-agent/README.org][org-agent (The Neurosymbolic Kernel)]]
- [[file:../SOUL.org][SOUL (Architectural Learnings & RCA)]]
- [[file:../gtd.org][GTD.org (Implementation Roadmap)]]