Tycoon Game Economy Design

SKILL.md - tycoon-game-economy-design v3.0.0

> Comprehensive skill registry documentation. This file is the single > source of truth for how skills are registered, resolved, executed, and > validated in this project. It is intended for contributors, auditors, > and anyone wiring the harness into a larger system.

1. At a glance

| Metric | Value | |--------|-------| | Skill name | tycoon-game-economy-design | | Version | 3.0.0 | | Domain | Game Economy Design & Virtual Market Balancing | | Architecture | Modular skill-registry + CoT router + hooks + tools + agents | | Determinism | Offline-first (zero network/LLM by default; seeded Monte Carlo) | | Sub-skills | 5 (requirements, evidence, core-analysis, knowledge, advisor) + 1 router | | Tools | 9 (economy, knowledge, evidence, context, harness) | | Quality gates | 10 (U1–U6 universal + G1–G4 domain), all enforced programmatically | | Output | Markdown report + JSON context + gate results |

2. Architectural overview

USER INPUT
   |
   v
Orchestrator (tools/orchestrator.py)
   |
   +-- Router.route()            -> RoutePlan (intent + ordered skills)
   +-- for each RouteStep:
   |      SkillRegistry.execute(skill, ctx, input)
   |         +-- validate input schema
   |         +-- Agent.__call__  (lifecycle hooks + tool calls)
   |         +-- validate output schema
   |         +-- context-window token accounting
   +-- QualityGateEngine.evaluate(ctx)   -> 10 gates + auto-fix
   +-- ReportRenderer.render(ctx, plan)   -> markdown report
   +-- emit run.end -> HarnessReport

Layered responsibilities (full diagram in assets/diagrams/architecture.md):

| Layer | Module | Responsibility | |-------|--------|---------------| | Config | tools/config.py + /config | Single source of truth: env, LLM, sim, flags | | Observability | tools/structured_logging.py | JSON/text structured logs, run_id, span context | | Errors | tools/errors.py | Hierarchy, retry, fallback chain, Result type | | Lifecycle | tools/hooks.py | Pre/post step, event emission, short-circuit | | Tools | tools/tool_registry.py | Schema-validated executable capabilities | | Skills | tools/registry.py | Register / resolve / execute / validate skills | | Routing | tools/router.py | Chain-of-thought intent → ordered plan | | Agents | tools/agents.py | Specialized sub-agents per skill | | Context | tools/context_window.py | Token budget, compaction, partitioning | | Orchestration | tools/orchestrator.py | Wires + runs the full pipeline | | Domain | tools/economy_simulator.py | Monte Carlo economy simulation | | Knowledge | tools/knowledge_updater.py + SECOND-KNOWLEDGE-BRAIN.md | Crawl + KB |

3. How skills are registered

A skill is a declarative contract between the markdown skill guidance (skills/*.md) and an executable agent. Registration is the act of binding a SkillSpec (name + description + agent + schemas + gates) into the SkillRegistry.

3.1 SkillSpec fields

| Field | Type | Purpose | |-------|------|---------| | name | str | Stable identifier (e.g. sub-core-analysis). | | description | str | One-line summary. | | agent | Callable[[ctx, input], artifact] | The executable. | | step | str | Harness step label (e.g. step_3). | | input_schema | JSON-Schema dict | Validates the input. | | output_schema | JSON-Schema dict | Validates the output. | | required_tools | tuple[str, ...] | Tools the agent expects. | | gates | tuple[str, ...] | Quality gates this skill contributes to. | | tags | tuple[str, ...] | Free-form tags for resolution queries. | | markdown_path | str \| None | The skills/*.md file (when loaded from disk). | | version | str | Skill version. | | metadata | dict | Arbitrary extra metadata. |

3.2 Registration methods

from tools.registry import SkillRegistry, SkillSpec
from tools.agents import CoreAnalysisAgent

registry = SkillRegistry()
registry.register(CoreAnalysisAgent().as_skill_spec())

# Or load markdown front-matter as no-op skills:
from tools.registry import load_skills_from_dir
load_skills_from_dir("skills", registry=registry)

register_all_agents(registry) (in tools/agents.py) registers all five executable sub-agents in one call. load_skills_from_dir can layer the markdown contracts on top via an agent_factory.

3.3 Built-in skill catalog

| Skill name | Step | Agent class | Required tools | Gates | |------------|------|-------------|----------------|-------| | sub-gather-requirements | step_1 | RequirementsAgent | harness.detect_language | – | | sub-evidence-collector | step_2 | EvidenceAgent | evidence.fetch_static | – | | sub-core-analysis | step_3 | CoreAnalysisAgent | economy.simulate | G1, G2, G3, G4 | | sub-knowledge-updater | step_4 | KnowledgeAgent | knowledge.query | – | | sub-advisor | step_5 | AdvisorAgent | – | – | | tycoon-game-economy-design | – | markdown no-op (loaded from main.md) | – | – |

A router skill (CoT) is documented in skills/router.md; its executable counterpart is tools/router.py::Router.

4. How skills are resolved

The SkillRegistry resolves skills by name, tag, step, or capability:

registry.get("sub-core-analysis")            # exact name
registry.resolve(tag="evidence")              # by tag
registry.resolve(step="step_3")               # by step
registry.resolve(capability="simulation")     # by capability
registry.require("sub-advisor")               # raise SkillNotFoundError if missing

The router (tools/router.py) is the high-level resolver: it takes raw user input, classifies the intent, and emits an ordered RoutePlan whose steps reference skills by name. See §6.

5. How skills are executed

SkillRegistry.execute(name, ctx, input_data, validate=True) runs a skill within a deterministic lifecycle:

1. Emit step.start hook.
2. Validate input_data against input_schema (if validate).
3. Call agent(ctx, input_data) inside safe_call (errors captured).
4. Validate the returned artifact against output_schema.
5. Emit step.end (or step.error) hook.
6. Account tokens via the context window manager.
7. Return a Result (Ok/Err) — never raises.

from tools.registry import execute_skill
result = execute_skill("sub-core-analysis", ctx, {"episodes": 500})
if result.is_ok:
    artifact = result.value

5.1 Input / output schemas

Schemas are JSON-Schema (draft-07) subsets. Bundled schemas live in assets/schemas/:

| Schema file | Skill | |-------------|-------| | requirements.json | sub-gather-requirements | | evidence.json | sub-evidence-collector | | core_analysis.json | sub-core-analysis | | knowledge.json | sub-knowledge-updater | | advisor.json | sub-advisor | | route_plan.json | router | | economy_spec.json | economy.simulate tool input |

The validator supports: type, properties, required, items, enum, minimum, maximum, minLength, maxLength, additionalProperties. Unknown keywords are ignored. See tools/tool_registry.py::_validate_schema.

5.2 Example: requirements artifact (input/output)

{
  "object": "Design a balanced coins+gems economy for a city builder",
  "scope": "full economy design + balance + progression + exploit resistance",
  "timeframe": "current / reference design",
  "available_inputs": ["coins", "gems", "faucet", "sink", "city builder"],
  "target_audience": "game economy designer / balance analyst",
  "language": "English",
  "analysis_type": "combined"
}

6. The chain-of-thought router

tools/router.py classifies intent and builds an ordered plan. Intent detection is deterministic (rule + keyword weights) so plans are reproducible. An optional intent_classifier callable lets a caller plug in an LLM-backed classifier.

6.1 Intents

full_analysis | simulate_only | academic_only | compare_specs | evidence_review | requirements_only | advisory_only | explain_method | ambiguous

Ambiguous intent resolves to the canonical full pipeline (safest default). The first step is always sub-gather-requirements.

6.2 RoutePlan shape

{
  "intent": "full_analysis",
  "steps": [
    {"step": "step_1", "skill": "sub-gather-requirements",
     "reason": "Always clarify object/scope/language before acting.",
     "optional": false, "inputs_from": []},
    {"step": "step_3", "skill": "sub-core-analysis", "reason": "...",
     "optional": false, "inputs_from": ["step_1"]}
  ],
  "cot_notes": ["Intent detected: full_analysis. ..."],
  "confidence": 1.0
}

7. Tools (registry)

Tools are schema-validated capabilities agents call instead of (or alongside) free-form LLM reasoning. Each tool declares name, description, executor, input_schema, output_schema, and metadata (timeout, retries, side-effects, cost, idempotent, tags).

tool_registry.invoke(name, input) returns a Result; it never raises. All tools are registered at import time via register_builtin_tools().

| Tool | Side effects | Cost | Purpose | |------|--------------|------|---------| | economy.simulate | read | cheap | Run Monte Carlo economy simulation. | | economy.default_spec | read | free | Return the canonical example spec. | | economy.spec_from_json | read | free | Load an EconomySpec from JSON. | | economy.validate_spec | read | free | Structurally validate a spec. | | knowledge.query | read | free | Query the knowledge brain for citations. | | knowledge.crawl | network | expensive | Run the crawl pipeline. | | evidence.fetch_static | read | free | Curated evidence bundle (fallback). | | context.estimate_tokens | none | free | Estimate token count. | | harness.detect_language | none | free | Detect Vietnamese/English. |

Prompt-rendering: tool_registry.to_prompt_list() produces the machine-readable tool catalog for LLM tool-use prompts.

8. Hooks (lifecycle)

tools/hooks.py provides a priority-ordered, error-isolated hook registry. Events (see HookEvent) include run.start/end, step.start/end/error, agent.invoke/result, tool.invoke/result/error, gate.check/fail/autofix, context.compact/checkpoint, degradation.escalate, knowledge.update, and custom.

from tools.hooks import register_hook, HookEvent, emit

register_hook(HookEvent.STEP_END, lambda p: print("done", p["step"]))
emit(HookEvent.STEP_END, {"step": "step_3"})

Abortable hooks can short-circuit an action (return False or raise AbortHook). install_builtin_hooks() wires structured logging into every core event. Hooks never crash the step that triggered them.

9. Context window management

tools/context_window.py enforces a per-run token budget with reserved output headroom. Entries carry a priority (LOW/NORMAL/HIGH/CRITICAL) and an evidence tier (1=best..4=weakest). When the budget is approached, the deterministic CompactionPolicy drops lowest-priority, lowest-tier, oldest entries first; critical entries are reserved.

from tools.context_window import ContextWindowManager, TokenBudget, ContextEntry, EntryPriority

mgr = ContextWindowManager(TokenBudget(capacity=120_000, reserve=8_000))
mgr.add(ContextEntry(id="e1", content="...", source="step_3",
                    tier=2, priority=EntryPriority.HIGH))
mgr.compact()          # free headroom
mgr.partition_text(big_text, max_chunk_tokens=4096, overlap_tokens=200)

Token estimation is tokenizer-free (calibrated heuristic) so budgeting is reproducible offline; a real tokenizer can be injected via TokenEstimator(tokenizer=...).

10. Quality gates

Ten gates are enforced after the plan executes (tools/orchestrator.py::QualityGateEngine). U1 and U2 have auto-fix handlers; failures after retries are recorded as explicit limitations rather than silently passing.

| Gate | Check | |------|-------| | U1 | ≥3 sources cited, ≥1 academic/authoritative | | U2 | Disclosure/limitations before recommendation | | U3 | Evidence hierarchy stated per source (Tier 1–4) | | U4 | Language matches user preference | | U5 | Output uses declared template (all sections) | | U6 | Every claim traceable to ≥1 source or flagged | | G1 | Faucets/sinks balanced (conservation check) | | G2 | Pricing/scarcity & progression defined | | G3 | Feedback loops & exploit resistance modeled | | G4 | Simulation present (inflation/exploit detection) |

11. Error handling & graceful degradation

tools/errors.py defines the exception hierarchy (HarnessError, StepError, ValidationError, ToolError, RouterError, ContextWindowExceededError, DegradationError), a Result type (Ok/Err), safe_call, retry (exponential backoff), and FallbackChain. Every tool invocation and every skill execution returns a Result; the orchestrator never propagates exceptions into the caller — failures degrade gracefully and are recorded in ctx["errors"] and ctx["limitation_notices"].

Degradation levels (0=full … 4=total failure) mirror skills/main.md.

12. Configuration

Layered, type-safe, immutable AppConfig (tools/config.py). Precedence: defaults .yaml < TYCOON_* env vars < explicit overrides. See config/README.md`.

13. Running

# v3 orchestrator
python tools/orchestrator.py --query "Design a balanced coins+gems economy" \
    --episodes 500 -o report.md

# scripts wrapper
python scripts/run_harness.py "..." -o report.md --context-out ctx.json

# seed the knowledge brain from curated references
python scripts/seed_knowledge.py

# crawl (dry-run by default)
python scripts/crawl.py --apply

# validate project integrity
python scripts/validate.py

# dump the registries
python scripts/list_registry.py --out registry.json

14. Testing

python -m pytest tools/                       # all unit tests
python tools/test_economy_simulator.py         # 41 tests
python tools/test_harness_runner.py            # 46 tests (v2)
python tools/test_knowledge_updater.py         # 19 tests
python tools/test_v3_modules.py                # v3 modules (registry, router, hooks, tools, agents, config, context_window, orchestrator)
python tools/run_test_scenarios.py            # 137 structural checks + live run

15. File contract (v3)

/
├── SKILL.md                       # this file (registry documentation)
├── CLAUDE.md                       # agent operating manual
├── PROJECT-detail.md               # technical specification
├── PROJECT-DEVELOPMENT-PHASE-TRACKING.md
├── SECOND-KNOWLEDGE-BRAIN.md       # living knowledge base
├── README.md, CHANGELOG.md, CONTRIBUTING.md, LICENSE
├── progression.json, pyproject.toml, requirements.txt
├── skills/                         # markdown skill guidance
│   ├── main.md
│   ├── router.md                   # CoT router skill
│   ├── sub-gather-requirements.md
│   ├── sub-evidence-collector.md
│   ├── sub-core-analysis.md
│   ├── sub-knowledge-updater.md
│   └── sub-advisor.md
├── tools/                          # executable v3 framework + legacy
│   ├── config.py, structured_logging.py, errors.py
│   ├── context_window.py, hooks.py
│   ├── tool_registry.py, registry.py, router.py
│   ├── agents.py, orchestrator.py
│   ├── economy_simulator.py, knowledge_updater.py
│   ├── context_manager.py, harness_runner.py (v2, kept)
│   ├── validate_project.py, run_test_scenarios.py
│   └── test_*.py
├── config/                         # type-safe YAML profiles
│   ├── default.yaml, production.yaml, test.yaml, README.md
├── scripts/                        # automation
│   ├── setup.py, seed_knowledge.py, run_harness.py
│   ├── crawl.py, validate.py, list_registry.py, README.md
├── references/                     # grounding material
│   ├── domain_knowledge.md, methods.md, sources.md, README.md
│   └── prompt_templates/*.md
├── assets/                         # static resources
│   ├── schemas/*.json
│   └── diagrams/architecture.md
├── tests/

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [dungnotnull](https://github.com/dungnotnull)
- **Source:** [dungnotnull/tycoon-game-economy-design-agent-skill](https://github.com/dungnotnull/tycoon-game-economy-design-agent-skill)
- **License:** MIT

Install and usage instructions live in the source repository linked above.