Contributing Guidelines

Contributing Guidelines

Why you contribute matters more than what you contribute.

---

Why Contribute?

0 — The Pain

Most open source dies. Not from bad code — from misaligned incentives.

Contributors burn out because their work gets absorbed by companies that extract value without returning it. Maintainers quit because governance degrades into politics. Projects fork because there's no protocol for collaboration.

FoundUps solves this at the root: the contribution model itself is built on ROC (Return on Compute), not ROI. Your contribution isn't equity that gets diluted. It's compute that compounds.

1 — The Solution

WSP protocols govern every contribution. They're not bureaucracy — they're the immune system that prevents the project from decaying into the patterns that kill open source.

When you contribute to FoundUps, you're not submitting code to a repo. You're adding a module to an ecosystem where every piece interoperates with every other piece across every FoundUp that will ever launch.

2 — The Outcome

Your module has a 100-year lifespan. Not because we're optimistic — because WSP compliance ensures it. Modules that follow the protocol survive the death of any individual maintainer, company, or funding source.

You become a 012: you saw the pain (0), you built the solution (1), you receive the outcome (2) — your work used across the ecosystem, compounding in value.

---

Getting Started

Environment Setup

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

# Set up development environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install pytest pytest-cov pytest-asyncio

# Verify everything works
python -m pytest modules/ -v
python tools/modular_audit/modular_audit.py modules/

Study Before Building

Before contributing, understand the existing patterns:

# Explore the enterprise domain architecture
ls modules/
cat modules/README.md

# Study successful modules in your area of interest
find modules/communication/ -name "*.py" | head -3 | xargs cat
find modules/ai_intelligence/ -name "*.py" | head -3 | xargs cat

Create a Clean State

from modules.wre_core.src.components.clean_state_manager import WSP2CleanStateManager
from pathlib import Path

csm = WSP2CleanStateManager(Path('.'))
result = csm.create_clean_state_snapshot('Starting my contribution')
print(f'Safe rollback point: {result["tag_name"]}')

---

What to Contribute

New Modules (Highest ROC)

Creating entirely new capabilities has the highest return on compute because new modules serve every FoundUp in the ecosystem.

High-priority areas:

Area	Why (The Pain)	What's Needed
Bitcoin/Lightning	FoundUps need decentralized value flow	Network integration modules
Social Adapters	012s need to reach communities where they are	Twitter, LinkedIn, YouTube automation
Agent Coordination	Swarms need multi-agent collaboration	Orchestration patterns
Testing Tools	WSP compliance must be automatic	Validation automation
Documentation	Knowledge must outlast its creators	Generator modules

Module Enhancement

Improve existing modules — performance optimization, feature completion, cross-module integration, error handling, documentation updates.

WSP Protocol Extensions

Evolve the framework: new protocols for emerging needs, better validation tools, metric collection for ecosystem health.

Agent Development

Build autonomous capabilities: domain-specific agents, cross-domain coordinators, QA agents, optimization agents.

---

Contribution Workflow

Phase 1: Discovery

# Identify the pain (0)
# Search existing issues and discussions
# Check if similar work exists
# Plan your approach — start with WHY this module must exist

Phase 2: Implementation

# Create feature branch
git checkout -b feature/your-contribution-name

# Use WSP 33 for module creation (if applicable)
cd modules/wre_core
python src/wre_core_poc.py
# Select option 2: "New Module Build"

# Follow WSP protocols throughout
python tools/modular_audit/modular_audit.py modules/
pytest modules/your_module/ --cov=modules.your_module.src --cov-report=term-missing

# Document as you go — README.md, INTERFACE.md, ModLog.md

Phase 3: Quality Assurance

# WSP compliance check
python tools/modular_audit/modular_audit.py modules/

# Test coverage (minimum 90%)
pytest modules/ -v --cov=modules --cov-report=term-missing

# Agent integration test (if applicable)
cd modules/wre_core
python src/wre_core_poc.py

# Clean state snapshot
python -c "
from modules.wre_core.src.components.clean_state_manager import WSP2CleanStateManager
from pathlib import Path
csm = WSP2CleanStateManager(Path('.'))
result = csm.create_clean_state_snapshot('Completed: your-contribution-name')
print(f'Completion snapshot: {result[\"tag_name\"]}')
"

Phase 4: Submission

# Commit with WSP-compliant messages
git add .
git commit -m "WSP: Add [module_name] - [brief_description]

- WSP 1: Modular design with clear interfaces
- WSP 3: Correctly placed in [domain] domain
- WSP 5: [X]% test coverage achieved
- WSP 6: All tests passing
- Implements: [specific_functionality]
- Dependencies: [list_dependencies]
- Agent Integration: [orchestration_capabilities]"

# Push and create PR
git push origin feature/your-contribution-name

---

WSP Compliance Requirements

Every contribution must comply with these standards. They're non-negotiable — not because we like rules, but because WSP compliance is why modules survive 100 years.

Mandatory Standards

WSP	Requirement	Why It Exists
WSP 1	Framework Principles — agentic responsibility, protocol-driven dev, recursive improvement, traceable narrative, modular cohesion	Because unstructured autonomy is chaos
WSP 3	Enterprise Domain Architecture — correct domain placement, clear interfaces, no hidden dependencies	Because coupling kills interoperability
WSP 4	FMAS Compliance — pass structural audit	Because structural decay is invisible until catastrophic
WSP 5	Test Coverage ≥90%	Because untested code is a liability to every FoundUp using it
WSP 6	All tests passing	Because one failing test means one broken FoundUp
WSP 7-10	Documentation — README.md, INTERFACE.md, ModLog.md, module.json	Because knowledge locked in one person's head dies with them

Structural Validation

# Must pass:
python tools/modular_audit/modular_audit.py modules/
# Result: "All modules passed structural compliance"

---

Making Your Module Agent-Ready

Your module will be orchestrated by agent swarms. Build it accordingly:

class YourModule:
    async def health_check(self):
        """Return current module health status."""
        return {
            "status": "healthy",
            "performance_metrics": self.get_performance_data(),
            "resource_usage": self.get_resource_usage(),
            "error_count": self.get_error_count()
        }

    async def handle_error(self, error, context):
        """Autonomous error handling and recovery."""
        if error.is_recoverable():
            return await self.attempt_recovery(error)
        else:
            return await self.graceful_degradation(error)

    async def execute_with_context(self, orchestration_context):
        """Execute within agent orchestration."""
        result = await self.primary_function(orchestration_context.input)
        orchestration_context.update_with_result(result)
        return result

Register with WRE orchestration:

from modules.wre_core.src.components.agentic_orchestrator.orchestration_context import OrchestrationTrigger

@register_orchestration_handler(OrchestrationTrigger.YOUR_TRIGGER_TYPE)
async def handle_orchestrated_workflow(context):
    return await your_module.execute_with_context(context)

---

What NOT to Contribute

Anti-Pattern	Why It's Wrong (Back to 0)
Platform-specific silos	Locks modules to one context. FoundUps need interoperability.
Proprietary dependencies	Creates vendor lock-in. Contradicts modular sovereignty.
Competitive features	Designed to exclude. ROC measures value created, not value captured.
Hidden interfaces	Prevents agent orchestration. Swarms can't use what they can't see.
Non-WSP code	Won't survive. 100-year lifespan requires protocol compliance.
Undocumented modules	Knowledge dies with the author. WSP 7-10 exist for a reason.

---

Recognition

Contributor Levels

Level	Contribution	Role in the Ecosystem
Module Contributor	Created or enhanced modules	Building the 1 (solution)
Agent Developer	Built autonomous capabilities	Scaling the swarms
Protocol Architect	Extended WSP framework	Strengthening governance
Ecosystem Gardener	Documentation, testing, quality	Maintaining coherence
Vision Ambassador	Spread mission, onboard others	Expanding the 012 network

ROC-Based Recognition

As the economic model matures, contributions will be tracked through decentralized attribution. Value flows based on module usage and impact — not on who has the most GitHub stars or the loudest voice.

Your contribution's ROC is measured by how much value it creates for the network, not how much value you extract from it.

---

Getting Help

Question	Where to Look
Which domain for my module?	Module Ecosystem
How to integrate with agents?	Agent System
WSP compliance details?	WSP Framework
Understanding the vision?	FoundUps Manifesto
Technical architecture?	WRE Core Engine

---

The Why, Summarized

You're not contributing to software. You're contributing to a system where every module compounds value across every FoundUp that will ever exist.

The pain (0): Open source contribution models are broken — burnout, extraction, fragmentation.

The solution (1): WSP-governed, ROC-measured, agent-orchestrated modules that interoperate by design.

The outcome (2): Your code runs in autonomous ventures for 100 years, and your contribution is recognized by the network — not by a company that might not exist next quarter.

Start with why your module must exist. The rest follows.

---

Home · Getting Started · WSP Framework · Module Ecosystem · FoundUps Manifesto