diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..23cd224 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,176 @@ +# polycode-sim — Agent Instructions + +## Repo Identity + +**Purpose:** PolyCode Simulator is a Python-based agent simulation modeling investor and voter strategies to study governance/allocation dynamics, with parameter sweeps and KPI aggregation. + +**Domain:** infotech +**Repo slug:** polycode-sim +**Topic ID:** `cee7bedf-2b48-46ef-8601-006474f2ad7a` +**Workplan prefix:** `POLYCODE-WP-` + +--- + +## State Hub Integration + +The Custodian State Hub tracks work across all domains. Interact via HTTP REST — +there is no MCP server for Codex agents. + +| Context | URL | +|---------|-----| +| Local workstation | `http://127.0.0.1:8000` | +| Remote via tunnel | `http://127.0.0.1:18000` | +| Optional local edge relay | http://127.0.0.1:18080 | + +When an operator has enabled the edge relay, set API_BASE to the relay URL. +Queueable writes return an explicit queued receipt if the central hub is +unreachable. Treat that as pending local evidence, then ask the operator to run +statehub outbox status/replay after connectivity returns. + +### Orient at session start + +```bash +# Offline brief — works without hub connection +cat .custodian-brief.md + +# Active workplans for this domain +curl -s "http://127.0.0.1:8000/workplans/?topic_id=cee7bedf-2b48-46ef-8601-006474f2ad7a&status=active" \ + | python3 -m json.tool + +# Check inbox +curl -s "http://127.0.0.1:8000/messages/?to_agent=polycode-sim&unread_only=true" \ + | python3 -m json.tool +``` + +Mark a message read: +```bash +curl -s -X PATCH "http://127.0.0.1:8000/messages//read" \ + -H "Content-Type: application/json" -d '{}' +``` + +### Log progress (required at session close) + +```bash +curl -s -X POST http://127.0.0.1:8000/progress/ \ + -H "Content-Type: application/json" \ + -d '{ + "summary": "what was done", + "event_type": "note", + "author": "codex", + "workplan_id": "", + "task_id": "" + }' +``` + +Omit `workplan_id` / `task_id` when not applicable. + +### Update task status + +```bash +curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ + -H "Content-Type: application/json" \ + -d '{"status": "progress"}' +# values: wait | todo | progress | done | cancel +``` + +### Flag a task for human review + +```bash +curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ + -H "Content-Type: application/json" \ + -d '{"needs_human": true, "intervention_note": "reason"}' +``` + +--- + +## Session Protocol + +**Start:** +1. `cat .custodian-brief.md` — domain goal and open workplans (offline-safe) +2. Check inbox: `GET /messages/?to_agent=polycode-sim&unread_only=true`; mark read +3. Scan workplans: `ls workplans/` — note `status: ready`, `active`, or `blocked` files and open tasks +4. Check human-needed tasks: `GET /tasks/?needs_human=true` + +**During work:** +- Update task statuses in workplan files as tasks progress +- Record significant decisions via `POST /decisions/` + +**Close:** +1. Update workplan file task statuses to reflect progress +2. Log: `POST /progress/` with a summary of what changed +3. After workplan file changes, run: + ```bash + statehub fix-consistency + ``` + Coding agents should run this directly; ask the operator only if the CLI or + State Hub API is unavailable. This syncs task status from files into the hub DB. + +--- + +{CREDENTIAL_ROUTING} + + + + +--- + +## Workplan Convention (ADR-001) + +Work items originate as files in this repo — not in the hub. The hub is a +read/cache/index layer that rebuilds from files. + +**File location:** `workplans/POLYCODE-WP-NNNN-.md` + +**Archived location:** finished workplans may move to +`workplans/archived/YYMMDD-POLYCODE-WP-NNNN-.md`. The `YYMMDD` prefix is +the completion/archive date; the frontmatter `id` does not change. + +**Ad Hoc Tasks:** small opportunistic fixes discovered during a session use +`workplans/ADHOC-YYYY-MM-DD.md` with task ids `ADHOC-YYYY-MM-DD-T01`, etc. Use +this only for low-risk work completed directly; create a normal workplan for +anything needing analysis, design, approval, dependencies, or multiple phases. + +**Frontmatter:** + +```yaml +--- +id: POLYCODE-WP-NNNN +type: workplan +title: "..." +domain: infotech +repo: polycode-sim +status: proposed | ready | active | blocked | backlog | finished | archived +owner: codex +topic_slug: ... +created: "YYYY-MM-DD" +updated: "YYYY-MM-DD" +state_hub_workstream_id: "" # written by fix-consistency — do not edit (legacy name; holds the workplan id) +--- +``` + +Use `proposed` for a new draft, `ready` after review against current repo +state, and `finished` after implementation. `stalled` and `needs_review` are +derived health labels, not frontmatter statuses. + +**Task block format** (one per `##` section): + +``` +## Task Title + +` ` `task +id: POLYCODE-WP-NNNN-T01 +status: wait | todo | progress | done | cancel +priority: high | medium | low +state_hub_task_id: "" # written by fix-consistency — do not edit +` ` ` + +Task description text. +``` + +Status progression: `todo` → `progress` → `done`; use `wait` for waiting/blocked work and `cancel` for stopped work. + +To create a new workplan: +1. Write the file following the format above +2. Run `statehub fix-consistency` locally; ask the operator only if the CLI or + State Hub API is unavailable. diff --git a/INTENT.md b/INTENT.md new file mode 100644 index 0000000..5c8b1b1 --- /dev/null +++ b/INTENT.md @@ -0,0 +1,23 @@ +**PolyCode Simulator** is a research/prototyping tool for exploring how different stakeholder behaviors affect governance and resource allocation outcomes. + +More concretely: + +**PolyCode Simulator** is a Python simulation system where different types of agents, especially **investors** and **voters**, follow configurable strategies. These agents interact inside a modeled governance or allocation environment. By changing parameters repeatedly, the simulator can explore many scenarios and collect KPIs that show how well different governance/allocation mechanisms perform. + +In practical terms, it should do four things: + +1. **Models actors** + Investors may allocate capital, back proposals, seek returns, or influence outcomes. Voters may support proposals, delegate votes, behave strategically, or vote based on preferences. + +2. **Models governance/allocation rules** + It studies how resources, funding, influence, votes, or rewards are distributed under different mechanisms. + +3. **Runs experiments** + Parameter sweeps mean it systematically varies assumptions such as number of voters, investor behavior, voting rules, capital distribution, turnout, strategy mix, incentives, or governance thresholds. + +4. **Aggregates results** + KPI aggregation means it summarizes outcomes across runs, for example efficiency, fairness, concentration of power, proposal success rate, capital allocation quality, voter satisfaction, resilience, or strategic exploitability. + +Polycode is a **simulation laboratory for mechanism design**: a way to test governance and funding systems before deploying them in the real world. + + diff --git a/README.md b/README.md index dc7b755..de811d7 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # PolyCode Simulator (v0.1) +Simulator for PolyCode Market Dynamics + ## Quickstart 1) Run a single demo simulation: diff --git a/SCOPE.md b/SCOPE.md new file mode 100644 index 0000000..f3e3a2f --- /dev/null +++ b/SCOPE.md @@ -0,0 +1,36 @@ +# SCOPE + +> This file was generated by `statehub register`. Refine it as the repository +> boundaries become clearer. + +## One-liner + +PolyCode Simulator is a Python-based agent simulation framework for studying governance and resource-allocation dynamics. It models investor and voter strategies, runs parameterized scenario sweeps, and aggregates KPIs to compare the behavior, robustness, and outcomes of different allocation mechanisms. + +## Core Idea + +Polycode is a simulation laboratory for mechanism design: a way to test governance and funding systems before deploying them in the real world. + +## In Scope + +- Core simulation engine for a single demo run +- Pluggable investor/voter strategy modules +- Parameter sweeps and KPI aggregation via experiments.py +- Baseline parameter configuration management +- Protocol specification documentation + +## Out of Scope + +- Production/live deployment integration +- Visualization dashboard or UI +- Cross-repo orchestration + +## Current State + +- {"project_description": "PolyCode Simulator is a Python-based agent simulation modeling investor and voter strategies to study governance/allocation dynamics, with parameter sweeps and KPI aggregation.", "intent_markdown": "# Intent\n\n## Purpose\nPolyCode Simulator (v0.1) is a Python simulation engine that models interactions between investor and voter agents under pluggable strategies, used to explore governance and capital-allocation dynamics and their emergent outcomes (KPIs) across parameter sweeps.\n\n## In Scope\n- Core simulation engine (`simulator.py`) running single demo simulations\n- Pluggable investor/voter strategy implementations (`strategies.py`)\n- Parameter sweep / grid-search experiments with KPI aggregation (`experiments.py`)\n- Baseline parameter configuration (`params_default.json`)\n- Protocol specification documentation (`spec.md`)\n- Run outputs written to `./runs/`\n\n## Out of Scope\n- Production deployment or live trading/voting integration\n- UI/dashboard for visualizing results\n- Multi-repo orchestration or external service integration\n\n## Current State\nEarly-stage (v0.1) simulator with a minimal CLI-driven workflow; single initial commit plus a CI smoke workflow.\n", "domain_slug": null, "topic_slug": "polycode-sim", "topic_title": "PolyCode Simulator", "repo_slug": "polycode-sim", "workplan_prefix": "POLYCODE-WP", "in_scope": ["Core simulation engine for a single demo run", "Pluggable investor/voter strategy modules", "Parameter sweeps and KPI aggregation via experiments.py", "Baseline parameter configuration management", "Protocol specification documentation"], "out_of_scope": ["Production/live deployment integration", "Visualization dashboard or UI", "Cross-repo orchestration"], "project_description": "PolyCode Simulator is a Python-based agent simulation modeling investor and voter strategies to study governance/allocation dynamics, with parameter sweeps and KPI aggregation.", "repo_slug": "polycode-sim", "topic_slug": "polycode-sim", "topic_title": "PolyCode Simulator", "workplan_prefix": "POLYCODE-WP"} + +## Getting Oriented + +- Start with: INTENT.md +- Agent instructions: AGENTS.md +- Workplans: workplans/ diff --git a/specs/PolyCodePitchDeck b/specs/PolyCodePitchDeck new file mode 100644 index 0000000..0cd18d8 --- /dev/null +++ b/specs/PolyCodePitchDeck @@ -0,0 +1,184 @@ +PolyCode + +*Predict. Invest. Build. Together.* + +# 📘 PolyCode — Pitch Deck (v0.1) + +--- + +## 1. Title Slide + +**PolyCode** +**The AI-Driven Market Where Code Funds Itself** +Predict. Invest. Build. Together. + +*(Logo placeholder)* + +--- + +## 2. The Problem + +Modern software development is: + +* Slow — coordination and funding bottlenecks stall innovation. +* Opaque — investors and contributors can’t see progress or ROI until it’s too late. +* Top-down — product priorities are decided by a few, not by the ecosystem that needs them. + +> **We need a market where ideas compete fairly and resources flow to what proves valuable.** + +--- + +## 3. The Vision + +**PolyCode** transforms software creation into a self-financing, self-correcting economy. +A decentralized platform where: + +* Ideas are posted as *issues*. +* Users invest and predict the effort required. +* AI agents implement once funding thresholds are met. +* Adoption validates success and triggers automatic payouts. + +> **Software builds itself — guided by markets, not managers.** + +--- + +## 4. How It Works (Simplified Flow) + +1️⃣ **Post an Idea** +→ Anyone creates an issue (feature, fix, or concept). + +2️⃣ **Invest & Predict** +→ Backers fund the idea and bet on required effort + time. + +3️⃣ **AI Implementation Begins** +→ When funding exceeds predicted effort, PolyCode assigns it to an AI developer instance. + +4️⃣ **Community Votes on Decisions** +→ AI proposes variants; investors vote. + +5️⃣ **Control Point Review** +→ At 50% budget use, progress is published — investors can withdraw or double down. + +6️⃣ **Deployment & Adoption Test** +→ Feature released under a flag. +→ If >50% of users keep it → accepted & payouts distributed. + +--- + +## 5. Reward Distribution (Example) + +| Recipient | Share | Motivation | +| --------------- | ---------------- | -------------------- | +| Top estimators | 10 % + 5 % + 1 % | Reward accuracy | +| Issue author | 10 % | Encourage creativity | +| Decision voters | 8 % | Reward participation | +| Investors | 50 % | Return on capital | +| Platform | up to 16 % | Sustain operations | + +--- + +## 6. Example Simulation Outcome + +From early **PolyCode Sim v0.1** runs: + +* 75 % of issues reach acceptance threshold. +* 20 % overspend frequency (indicates healthy risk dispersion). +* Decision-quality correlation = +0.42 with adoption (market voting works). +* Manipulation-proxy < 0.1 mean (robust estimate integrity). + +> Simulation validates that **market feedback can guide AI development efficiently**. + +--- + +## 7. Technology Stack + +| Layer | Description | +| -------------------- | ------------------------------------------------------------ | +| **PolyCode Sim** | Agent-based simulator for economic tuning | +| **Core Protocol** | Funding, betting, voting, payout logic | +| **AI Agents** | Claude Code / OpenAI Codex / local LLMs | +| **Governance Layer** | DAO-like voting & reputation system | +| **Telemetry** | Live metrics from production feed simulator for optimization | + +--- + +## 8. Competitive Landscape + +| Model | Example | Limitations | PolyCode Advantage | +| -------------------- | ------------------ | ------------------------ | ------------------------------- | +| Freelance Platforms | Upwork, Fiverr | Manual, trust-based | Automated, prediction-verified | +| Crowdfunding | Kickstarter | No delivery verification | Code shipped + adoption proof | +| Open Source Bounties | Gitcoin | Low iteration speed | Continuous, AI-assisted cycles | +| AI Dev Tools | Replit Ghostwriter | No funding market | Integrated economy + governance | + +--- + +## 9. Economic Engine + +PolyCode introduces **three internal currencies**: + +| Token | Function | +| ----------------- | -------------------------------------------------- | +| **$VIBE / $WORK** | Implementation energy — tokens representing effort | +| **$BET** | Prediction stakes for estimating scope and time | +| **$IMPACT** | Earned reputation for successful participation | + +A balanced micro-economy ensures liquidity, accountability, and transparent reward flows. + +--- + +## 10. Business Model + +1. **Transaction fees** on each completed issue (platform share). +2. **Premium analytics / dashboards** for investors and DAOs. +3. **Enterprise integration** — companies host private PolyCode markets. +4. **Token appreciation** via protocol usage and staking. + +--- + +## 11. Go-to-Market Plan + +* **Phase 1:** Closed beta with AI-assisted open-source repos. +* **Phase 2:** Public market for micro-features. +* **Phase 3:** Enterprise & DAO integration. +* **Phase 4:** On-chain economy with live telemetry feedback. + +--- + +## 12. Team & Ecosystem + +* **Founder:** Bernd Worsch — Product strategist, hybrid-post innovator, AI systems architect. +* **Core Collaborators:** AI agents, open-source devs, research partners. +* **Allies:** Coulomb ecosystem (Charges & Joules currencies), KaizenAgentic framework. + +--- + +## 13. Traction & Next Steps + +✅ Simulation engine operational. +✅ Parameter optimization underway. +🔜 Beta testers onboarding Q1 2026. +🔜 Telemetry loop integration for adaptive tuning. + +> **We’re validating an entirely new way to build software.** + +--- + +## 14. The Ask + +We are seeking: + +* **€500 k** pre-seed for platform launch & compliance. +* Partnerships with **AI infrastructure providers** and **early-stage DAOs**. +* Strategic advisors in **game theory**, **token economics**, and **open-source ecosystems**. + +--- + +## 15. Closing + +> “In PolyCode, ideas don’t wait for permission — +> they attract belief, code themselves, and prove their worth.” + +**polycode.ai** | *Predict – Invest – Build – Together* + +xxx diff --git a/workplans/POLYCODE-WP-0001-statehub-bootstrap.md b/workplans/POLYCODE-WP-0001-statehub-bootstrap.md new file mode 100644 index 0000000..6dd16f4 --- /dev/null +++ b/workplans/POLYCODE-WP-0001-statehub-bootstrap.md @@ -0,0 +1,59 @@ +--- +id: POLYCODE-WP-0001 +type: workplan +title: "Bootstrap State Hub integration" +domain: infotech +repo: polycode-sim +status: ready +owner: codex +topic_slug: custodian +created: "2026-07-08" +updated: "2026-07-08" +state_hub_workstream_id: "05e27f85-6a20-4906-a3c1-633776d6c448" +--- + +# Bootstrap State Hub integration + +PolyCode Simulator is a Python-based agent simulation modeling investor and voter strategies to study governance/allocation dynamics, with parameter sweeps and KPI aggregation. + +## Review Generated Integration Files + +```task +id: POLYCODE-WP-0001-T01 +status: todo +priority: high +state_hub_task_id: "d0f6a1cd-641f-4a63-890c-99bc5c12cc4b" +``` + +Review `INTENT.md`, `SCOPE.md`, `AGENTS.md`, and `.custodian-brief.md`. +Replace generated placeholders with repo-specific facts where needed. + +## Verify Local Developer Workflow + +```task +id: POLYCODE-WP-0001-T02 +status: todo +priority: high +state_hub_task_id: "6ad22e61-ad4d-4643-ad49-000e41e4959b" +``` + +Identify the repo's install, test, lint, build, and run commands. Add or refine +those commands in the agent instructions so future coding sessions can verify +changes confidently. + +## Seed First Real Workplan + +```task +id: POLYCODE-WP-0001-T03 +status: todo +priority: medium +state_hub_task_id: "d0d8fea2-28e8-4766-8295-9118a8378c2c" +``` + +Create the first implementation workplan for the repository's most important +next change. After workplan file updates, run the sync locally from this repo +checkout: + +```bash +statehub fix-consistency +```