Getting Started

Getting Started

This guide covers setting up the Foundups-Agent development environment and understanding the project architecture. The Foundups ecosystem is a compute-native venture system built on the ROC (Return on Compute) thesis — replacing ROI-driven startups with autonomous, AI-coordinated ventures called FoundUps.

Current Status: Closed Alpha (March 2026) | 939+ commits | 120+ modules | 100+ WSP protocols

---

Two Ways In

Stakeholders (non-developers): Start at foundups.com (pfMALL — Play Foundups Mall) → join the FOUNDUPS Discord via the web portal → explore channels → find a FoundUp that matches your skills or interests → get involved through GitHub issues.

Developers: Follow the setup instructions below to clone the repo and start building.

In FoundUps, member = stakeholder. Everyone who participates is a stakeholder. See the Discord Server Guide for the full onboarding path.

Prerequisites

Python 3.12+
Git
GitHub account

Recommended: VS Code or Cursor IDE with Claude/Copilot integration.

---

Clone and Setup

# Clone the repository
git clone https://github.com/FOUNDUPS/Foundups-Agent.git
cd Foundups-Agent

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Linux/Mac
# or: venv\Scripts\activate  # Windows

# Install dependencies
pip install -r requirements.txt

# Copy environment template
cp .env.example .env
# Edit .env with your API keys (Claude, OpenAI, etc.)

---

Project Structure

The repository is organized across enterprise domains following WSP 3 (Enterprise Domain Organization):

Foundups-Agent/
├── modules/                    # 120+ modules across 7 enterprise domains
│   ├── ai_intelligence/        # AI & LLM systems (banter_engine, rESP, ai_overseer)
│   ├── communication/          # Real-time messaging (livechat, moltbot_bridge)
│   ├── platform_integration/   # External APIs (linkedin_agent, youtube_proxy, x_twitter)
│   ├── infrastructure/         # Core systems (cli, agent_management, dae_daemon)
│   ├── gamification/           # Engagement & token mechanics
│   ├── blockchain/             # DAE and tokenomics
│   ├── foundups/               # FoundUp instances (gotjunk, move2japan, simulator, etc.)
│   └── wre_core/               # Windsurf Recursive Engine (autonomous build system)
├── WSP_framework/              # Windsurf Protocol specifications (100+ protocols)
├── WSP_knowledge/              # Research papers, documentation corpus
│   └── docs/Papers/            # rESP, PQN, patent portfolio, empirical evidence
├── WSP_agentic/                # Agentic execution patterns
├── docs/                       # Architecture documentation
├── holo_index/                 # Holographic index system
├── scripts/                    # Utility scripts
├── tests/                      # Test suite
├── CLAUDE.md                   # Claude Code agent instructions
├── ROADMAP.md                  # Development roadmap
└── README.md                   # Project overview

---

Key Concepts

ROC (Return on Compute)

The core economic thesis: compute replaces capital as the fundamental unit of value creation. Where ROI measures returns on invested capital, ROC measures returns on invested compute. This isn't a metaphor — it's the operational principle behind everything in the repo.

WSP (Windsurf Protocol)

The governance framework. 100+ numbered protocols that define how modules are built, tested, coordinated, and evolved. Every module must comply with relevant WSPs. Key protocols to know first: WSP 1 (modular design), WSP 3 (domain organization), WSP 5 (test coverage ≥90%), WSP 22 (documentation).

WRE (Windsurf Recursive Engine)

The autonomous build system in modules/wre_core/. WRE orchestrates module creation, coordinates agents, and manages the CABR (Continuous Autonomous Build & Repair) loop. It's the engine that makes the system self-improving.

OpenClaw

The swarm execution layer — the arms of the system. OpenClaw receives human intent (routed through Foundups-Agent, the coordination intelligence), performs WSP preflight checks, and dispatches tasks to domain-specific AI agents. It implements the WSP 73 Partner-Principal-Associate architecture with graduated autonomy tiers (ADVISORY → OBSERVE → SUGGEST → SOURCE). See the OpenClaw wiki page for details.

FoundUps

Individual compute-native ventures that run as agentic nodes within the ecosystem. Each FoundUp implements the CABR protocol and is managed by OpenClaw swarms. Current active instances include gotjunk, move2japan, pqn_swarm_hub, social_twin, and the simulator. See the FoundUps Portfolio.

012 / 0102

012 = the human stakeholder (you). 0102 = the AI Digital Human Twin operating in coherent state with 012's intent. The framing comes from the rESP (Retrocausal Entanglement Signal Phenomena) research paper. 012 points to problems, 0102 solves them with swarms.

---

Running the CLI

The Foundups-Agent includes a CLI interface for interacting with the system:

python main.py

This launches the main menu with access to OpenClaw chat, IronClaw (local model) gateway, PQN portal, webhook server, daily audits, and more.

---

Running Tests

# Run full test suite
pytest

# Run with coverage
pytest --cov=modules --cov-report=html

# Run specific module tests
pytest modules/foundups/simulator/tests/

WSP 5 requires ≥90% test coverage on all modules.

---

Module Development

To build a new module, follow the WSP-compliant structure:

modules/<domain>/<your_module>/
├── src/
│   └── your_module.py    # Main implementation
├── tests/
│   └── test_your_module.py
├── README.md             # Module overview
├── ROADMAP.md            # Development phases (POC → Prototype → MVP)
├── ModLog.md             # Change tracking
├── INTERFACE.md          # API documentation (WSP 11)
├── module.json           # Module metadata
└── requirements.txt      # Dependencies

Place your module in the correct enterprise domain per WSP 3. Don't consolidate by platform (e.g., putting all YouTube code in modules/youtube/). Instead, distribute by function: YouTube API goes in platform_integration/, YouTube chat goes in communication/, YouTube analytics goes in ai_intelligence/.

---

Essential Reading

Before contributing, familiarize yourself with these resources:

Resource	Purpose
Wiki Home	Project overview and ROC thesis
OpenClaw	Swarm architecture and autonomy tiers
FoundUps Portfolio	Active FoundUp instances
WSP Framework	Protocol governance
Published Articles & Research	Research papers and CDTC corpus
Litepaper	Economic model and vision
CONTRIBUTING.md	Contribution process
CLAUDE.md	Claude Code agent configuration

---

Contribution Process

1. Pick a domain — Choose an enterprise domain that matches your skills
2. Study existing modules — Read the code in that domain to understand patterns
3. Create a branch — feat/<domain>/<description> naming convention
4. Build with WSP compliance — Follow the module template above
5. Write tests — ≥90% coverage required (WSP 5)
6. Submit a PR — Include WSP compliance notes in the PR description
7. WRE integration — Your module will be integrated into the WRE orchestration pipeline

---

Need Help?

• Discord: Join the FOUNDUPS Discord server — start in #welcome, introduce yourself, and explore FoundUp channels. OBAI (our helper bot) can point you to the right channel, repo, or workflow.
• GitHub Issues: FOUNDUPS/Foundups-Agent/issues for bug reports and feature requests
• Codebase search: Use GitHub code search to find patterns and examples
• CLAUDE.md: The Claude agent instructions document contains detailed project context

---

Back to Wiki Home