---

Project Kickoff: The MECA Initiative

To: The Development Team

From: Project Management

Date: October 27, 2023

Subject: Kickoff for the Metaprogramming-Enabled Component Architecture (MECA) Initiative

Team,

Good morning. After a series of highly productive design sessions, we are officially kicking off the MECA Initiative today. I want to thank everyone for their contributions in shaping what has become a truly innovative and compelling vision. We've moved from a nebulous idea to a solid architectural blueprint, and now it's time to bring it to life.

1. The Project Mission: Our "Why"

Let's quickly reaffirm our mission. We are building MECA to fundamentally change how we, and our AI assistants, build software. Our goal is to create a "control plane" for our codebase that constrains agents to safe, pre-defined operations and accelerates development by providing a high-level, domain-specific language (DSL) for common tasks.

We are moving away from the fragile "AI writes code" model and pioneering a "AI operates a system" model. Success means faster, more reliable feature development, a self-documenting set of architectural patterns, and a significant competitive advantage in leveraging agent-based AI.

2. The High-Level Plan: Our "How"

We will execute this project in three distinct, sequential phases. Each phase delivers concrete value and serves as a stable foundation for the next. Our strategy is incremental and pragmatic; we will build the tooling within our existing monorepo, ensuring zero disruption to ongoing work.

Phase I: The Foundation - "Building the Workbench"

• Objective: Establish the core infrastructure and prove the basic plumbing of the system. We end this phase with a working, albeit simple, CLI that can read information about our project.
• Key Deliverables:
  1. Workspace Scaffolding: Create a new meca workspace within our monorepo, housing our three core packages: core, cli, and ops. This isolates the framework's code from our application code.
  2. The Project Abstraction: In meca-core, implement the first version of our high-level Project class. Leveraging ts-morph, this class will be responsible for discovering our pnpm workspaces (sandbox, packages, etc.) and the packages within them.
  3. The "Hello, World" CLI: In meca-cli, build the initial meca command. It will have a single, read-only subcommand (meca ws list) that uses the meca-core Project class to list the discovered workspaces. This validates our entire toolchain, from CLI entry point to core library logic.

Phase II: The Engine - "Making It Do Something"

• Objective: Implement the first state-changing operations and the foundational transactional engine. We end this phase with the ability to safely and programmatically create a new, fully scaffolded experiment.
• Key Deliverables:
  1. The createExperiment Operation: Build our first "Level 4" operation. This will be the flagship feature of this phase, providing a one-shot command (meca create experiment) to generate a new, well-structured package in the sandbox.
  2. The Foundational TxContext: Implement the initial version of our TxContext. At first, it may focus on file-system-level atomicity (e.g., writing to a temp directory). This is where we abstract away raw fs calls.
  3. The First AST-Based Helper: To prove our ts-morph integration, we will build a simple "Layer 1" helper within our TxContext—likely an addImport function—and write robust unit tests for it.

Phase III: The Flywheel - "Making It Smart"

• Objective: Turn our engine into a self-improving system. We will build the tools that allow us to easily add new capabilities to the MECA framework. We end this phase with a complete, end-to-end workflow for an agent.
• Key Deliverables:
  1. The MPI System: Formalize the Metaprogramming Interface. This involves building the discovery mechanism (meca list mpi) and the execution logic within the TxContext that can dynamically invoke a handler from a component's .meta.ts file.
  2. The First Composed Operation: We will build our first "smart" operation that composes others, likely web.integrateExperiment. This operation will use our transactional context to perform multiple steps: modifying a package.json and then using an MPI operation to modify a .tsx file to import and render the new component.
  3. The Graduation Pipeline: Implement the meca promote command. This will be the capstone feature, providing the full lifecycle from sandbox to packages, including validation, file promotion, and MPI stripping.

3. Our Approach and Guiding Principles

• Leverage, Don't Reinvent: We will lean heavily on ts-morph for its codebase-aware AST capabilities. Our job is to build the semantic, transactional, and workflow layers on top of it.
• Test-Driven: The logic for AST manipulation is precise and can be brittle. We will commit to a strong testing culture from day one, especially for our core helpers and MPI operations.
• Incremental Value: Each phase is designed to be usable. By the end of Phase II, we will already have a tool that is genuinely useful for our team.

This is an ambitious project, but one that is well within our capabilities. The blueprint is solid, and the path forward is clear. Let's get started with Phase I and build the workbench.

Any final questions before we dive in?