---
name: one-person-company
description: "Build or retrofit a product as an autonomous one-person company (شرکت یک‌نفره): owner decides, AI agents execute. Use when starting a new project in this workspace, retrofitting an existing one (Rasato is next), or when the user mentions شرکت یک‌نفره, سامانه, ایجنت سوپرادمین, گزارش عملکرد, دفتر کار ایجنت, مدیریت تغییر, کنترل کیفیت, داشبورد سوپرادمین, or asks to make a project independent, measurable and self-reporting. Gives the philosophy, architecture blueprint, bootstrap and retrofit checklists, and templates; reference implementation is rasa-prompt/."
license: MIT
metadata:
  version: 1.0.0
  author: Rasa (owner) with Claude
  reference: rasa-prompt/ (RasaPrompt, https://rasa-promt.ir)
  based-on: coo-advisor, change-management, data-quality-auditor, revenue-operations (alirezarezvani/claude-skills, MIT)
---

# One-Person Company OS · سامانهٔ شرکت یک‌نفره

A product run by **one owner and a team of AI agents**. The owner sets direction, approves money and policy, and reads reports.
Agents execute every recurring job. Each agent has a clear role, a schedule, KPIs, a work ledger, and a manager agent that reports to the owner.
The reference implementation is `rasa-prompt/`. Read its `AGENTS.md` and `docs/12-company-os.md` before building.

## Philosophy (non-negotiable)

1. **Owner decides, agents execute.** Anything an agent does automatically is reversible (archive, disable, never delete) and logged with *why*.
2. **Independent per project.** Each project has its own repo folder, web app, Telegram bot (with an admin desk inside), channel, super-admin dashboard, settings and secrets. Projects only cross-promote.
3. **Measured.** Every agent run is recorded: time, success or error, output summary, AI calls and tokens. KPIs have targets and traffic lights.
4. **Reported.** A super-admin agent ("chief") sends the owner a daily brief and a weekly review in three layers:
   - a graphic card;
   - a short summary;
   - a private link to a detailed report with charts, trends compared with the last report, the agent table, AI credit, QA findings and changes.
5. **Quality over quantity.** Every category has fixed inventory with a quality floor. Weak sources switch themselves off, and daily QA runs with a score.
6. **Change management.** Every change (setting, source, product, deploy, decision) is recorded with what, why and who. Too many changes per week raises a change-fatigue warning. Code changes go in CHANGELOG and structural choices in DECISIONS.
7. **Revenue is a first-class department.** Real payment gateway (in Iran: Zibal or Zarinpal; never Telegram Stars). Sandbox never delivers the full product. Revenue KPIs sit in every report.
8. **Handoff-ready.** Every change updates `AGENTS.md`, `docs/` and `CHANGELOG.md` in the same commit, so any other agent can continue without asking.
9. **Secrets never in chat.** Merchant IDs and tokens are entered only through the dashboard's secrets form (write-only, never displayed or logged).
10. **Persian-first, formal «شما».** Correct ZWNJ, Persian ی and ک, and Persian digits in UI. Minimal, modern, lively design.

## Architecture blueprint

| Module | Responsibility | RasaPrompt file |
|---|---|---|
| Org registry | agents → (label, department, schedule, duty); departments → lead and KPIs; KPI targets | `services/org.py` |
| Agent runner + ledger | `agent_job(name, fn, trigger)` wraps every run and writes `AgentRun` | `main.py`, `models.AgentRun` |
| AI usage + credit | ContextVar counter per run; provider usage over 30 days; remaining against the owner's monthly budget | `services/ai.py` |
| Chief (super-admin agent) | daily brief, weekly review, ≤3 data-backed actions | `services/chief.py` |
| Report view | PNG card (KPI tiles, sparklines, inventory bars) and private HTML page `/r/{token}` with SVG charts | `services/report_view.py` |
| QA | sampled content checks, page health, revenue config, auto-fix of safe issues, score out of 100 | `services/qa.py` |
| Change log | `changes.record(title, kind, actor, why)` | `services/changes.py`, `models.ChangeEntry` |
| Content team | scout → analyst → editor → creator, each a step with a quality gate | `services/team.py` |
| Intake | the owner sends any link in the bot and an agent evaluates and imports it | `services/intake.py`, `bot/handlers/admin.py` |
| Curator | live ranking, fixed inventory caps, archive, source health and auto-disable | `services/curator.py` |
| Revenue | products, orders, gateway abstraction | `services/shop.py`, `services/pay.py` |
| Command center | full-control web dashboard: company/KPIs, departments and agent stats, reports, changes, money and secrets, team, content, settings with a "why" field | `web/admin.py`, `templates/admin.html` |
| Admin desk in bot | `/admin`: sources, inventory, team report, one-time dashboard login link, link intake | `bot/handlers/admin.py` |

Cadence (from coo-advisor):

| Rhythm | Work |
|---|---|
| Continuous | operational agents |
| Daily | QA, then the morning brief |
| Weekly | business review, retrospective and next priorities |
| Monthly | OKR and priority review with the owner |

## Bootstrap checklist (new project in this workspace)

1. Create a separate folder `trends288/<project>/` with its own git repo, `.env` prefix and systemd service. Never share a bot token with another project.
2. Copy the skeleton pieces from `references/templates.md`:
   - `AGENTS.md`
   - `docs/README.md`
   - `docs/12-company-os.md`
   - `docs/13-agents-reference.md`
   - `CHANGELOG.md`
   - `DECISIONS.md`
3. Implement in this order. Each step needs tests before moving on.
   1. Models: domain models plus `AgentRun`, `ChangeEntry`, `Report` and `Setting`. Settings get live overrides through `runtime_settings`.
   2. Runner: `org.py` and `agent_job`. No agent runs outside the ledger.
   3. AI: `ai.py` with the usage counter, `credit()` and a daily call cap.
   4. Chief and QA: `chief.py`, `report_view.py` and `qa.py`, plus the `/r/{token}` route.
   5. Command center: secrets form, KPI rows, departments, reports and changes.
   6. Bot: admin desk with `is_admin` from `owner_tg_id` and `admin_ids`.
   7. Revenue: products, gateway and sandbox-safe delivery.
   8. Domain agents (the actual product work).
4. Define 8–12 KPIs with targets in `org.KPIS`. Each department owns at least one.
5. Deploy with a backup-first script, then a health check, then send the first report to the owner.
6. Write the first CHANGELOG entry and DECISIONS rows.

## Retrofit checklist (existing project, e.g. Rasato)

1. Inventory the existing jobs and agents and map them into `org.AGENTS` departments.
2. Wrap every scheduled job with `agent_job` (ledger plus AI usage).
3. Add `ChangeEntry` and hook it into settings saves, automatic decisions and deploys.
4. Add QA checks specific to the product. For Rasato: download success rate, gateway live, bot heartbeat, page health, queue depth.
5. Add chief reports with KPIs. For Rasato: downloads per day, success rate, paid orders, revenue, active passes, errors per platform.
6. Add command-center sections and a secrets form; remove secrets from chat-based flows.
7. Write `AGENTS.md`, `docs/12-company-os.md` and `docs/13-agents-reference.md`, then update CHANGELOG and DECISIONS.
8. Send the first report and confirm with the owner.

## Report spec (what "good" means)

- **Glanceable:** each KPI shows its value, target, a traffic light (🟢 at or above target, 🟡 at or above 70% of target, 🔴 below) and an arrow against the previous report (▲▼, green when better).
- **Visual:** a PNG card about 1280×760 with KPI tiles, two 14-day sparklines and inventory-versus-cap bars.
- **Detailed:** a private link (random token, noindex) to an HTML page containing:
  - all KPIs;
  - recommended actions;
  - four 14-day SVG charts;
  - an agent table (success rate bar, average time, AI calls, tokens, last error);
  - AI credit;
  - inventory;
  - QA findings;
  - the change timeline.
- **Honest:** actions come only from data, at most three, revenue blockers first, with no invented percentages. If the AI is down, the report is sent without actions.
- **Independent:** the report is sent by the project's own bot (`report_bot=main`).

## Pitfalls learned

- Shell heredocs turn `\n` inside Python into real newlines. Write code containing backslashes with file-edit tools.
- Jinja needs `0.7`, not `.7`.
- Telegram captions are limited to 1024 characters; send the card with a short caption and keep the details on the linked page.
- Provider "credit" APIs rarely expose a wallet balance. Read 30-day usage (`/v1/dashboard/billing/usage` in OpenAI format, in cents) and compare it to the owner's budget.
- Unauthenticated GitHub search allows about 60 requests per hour; take an optional read-only token through the secrets form.
- Never auto-delete. Archive with a reason and a capped number per run.

## Roadmap in this workspace

1. RasaPrompt: reference implementation, finishing.
2. **Rasato** (`darban-live/`): next, using the retrofit checklist.
3. At least four more projects, each a separate folder and repo, all built with this skill from the first commit.

See `references/templates.md` for copy-ready skeletons.