# Tycoon Game Economy Design

> |

- **Type:** Skill
- **Install:** `agentstack add skill-dungnotnull-tycoon-game-economy-design-agent-skill-tycoon-game-economy-design-agent-skill`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [dungnotnull](https://agentstack.voostack.com/s/dungnotnull)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [dungnotnull](https://github.com/dungnotnull)
- **Source:** https://github.com/dungnotnull/tycoon-game-economy-design-agent-skill

## Install

```sh
agentstack add skill-dungnotnull-tycoon-game-economy-design-agent-skill-tycoon-game-economy-design-agent-skill
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

```python
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:

```python
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.

```python
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)

```json
{
  "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

```json
{
  "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`.

```python
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.

```python
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

```bash
# 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

```bash
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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-dungnotnull-tycoon-game-economy-design-agent-skill-tycoon-game-economy-design-agent-skill
- Seller: https://agentstack.voostack.com/s/dungnotnull
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.