albertomartureloalbertomarturelo/sii/CLAUDE.md

sii

CLAUDE.md18 starsChanged 17 days agoMITView on GitHub

A TypeScript monorepo that automates routine interactions with Chile's tax authority (SII — Servicio de Impuestos Internos) for a single user acting on their own RUT, plus the empresas that user is authorized to represent. One shared domain core (@albertomarturelo/sii-core) backs two surfaces: a human CLI and an MCP server. The MCP server (stdio) is the integration point for both Claude Code and Claude Desktop; the CLI serves the terminal and is also what Claude Code can drive via Bash.…

Reads credentials

In this repository8 other files it gives its agents.
- issue-newSkill
- issue-startSkill
- new-decisionSkill
- review-prSkill
- run-siiSkill
- session-closeSkill
- session-startSkill
- validate-contextSkill

The file

We split this CLAUDE.md into the rules it gives an agent

2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
Never hard-code a SII hostname: Read from @albertomarturelo/sii-core config.
line 50
Distinctive:
No third-party SII libraries: Every selector, endpoint, and payload shape is derived from first-hand observation of the live SII surface …
line 64

≈ “Common” is an estimate: at least 1 in 5 of the 26,980 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

CLAUDE.md

Project: sii — TypeScript core + CLI + MCP for SII Chile

What This Project Does

A TypeScript monorepo that automates routine interactions with Chile's tax authority (SII — Servicio de Impuestos Internos) for a single user acting on their own RUT, plus the empresas that user is authorized to represent. One shared domain core (@albertomarturelo/sii-core) backs two surfaces: a human CLI and an MCP server. The MCP server (stdio) is the integration point for both Claude Code and Claude Desktop; the CLI serves the terminal and is also what Claude Code can drive via Bash. The core holds every legal and operational guardrail, so those rails apply regardless of which surface is in front.

This is a ground-up TypeScript rewrite of the proven Python sii-cli; the hard-won SII wire knowledge and guardrails are PORTED, the code is not.

Architecture

@docs/ARCHITECTURE.md

Tech Stack

@docs/STACK.md

Conventions

@docs/CONVENTIONS.md

Roadmap

@docs/ROADMAP.md

Key Decisions

@docs/decisions/_index.md

Build & Run

Install: pnpm install
Build all packages: pnpm build (tsc -b)
Typecheck: pnpm typecheck
Test: pnpm test (vitest)
Lint / format: pnpm lint / pnpm format
One package: pnpm --filter @albertomarturelo/sii-core <script>

Critical Rules

Never hard-code a SII hostname. Read from @albertomarturelo/sii-core config. Prod is the only target; there is no env switch (ported from sii-py ADR-016). (ADR-004)
Surfaces call @albertomarturelo/sii-core tasks only. The CLI and MCP NEVER reach past the task layer into the portal/DTE facades — that bypasses throttling, the audit log, and credential handling. (ADR-003)
External dependencies go through injectable seams. The SII portal driver, secret store, session store, audit sink, and clock are interfaces with Node default implementations, so unit tests substitute fakes and never touch the real SII / keyring / clock. The core is a Node library otherwise. (ADR-003)
Secrets never touch disk in plaintext and never reach the LLM. The Clave Tributaria is typed by the user into SII's real page (browser login, cookies-only) or held in the OS keyring (CLI only). No password ever crosses an MCP tool argument. Never commit *.pfx, *.p12, .env, or anything under .sii/. (ADR-006)
No third-party SII libraries. Every selector, endpoint, and payload shape is derived from first-hand observation of the live SII surface and cited in a code comment. (ADR-004)
Decisions get an ADR BEFORE implementation. About to add a dependency, move a layer boundary, or pick between plausible patterns? Run /new-decision first. (ADR-001 / CFD)
Corrections become conventions. Fix the same pattern twice → write it into docs/CONVENTIONS.md in the same commit.
Identity is single-account + operate-centric. One live session at a time (switch by logout→login); within it, a persona account's operate pointer selects which RUT it acts as (self by default; an empresa it represents). Empresa accounts cannot represent anyone. (ADR-005)
Absolute rule — no AI attribution anywhere. Claude, GPT, Copilot, or any AI tool must NEVER appear as co-author, generator, or reference in commits, PR titles/bodies/comments, issues, branch names, code comments, docs, or any artifact that lands in git or on GitHub. Authorship is the human owner.

<!--
This file is the INDEX, not the encyclopedia. Adding paragraphs here? Move them
to a docs/*.md file and @reference it. Target ≤150 lines.
CFD procedures are Agent Skills in .agents/skills/ (.claude/skills is a symlink to
it) — run /session-start at the start of a session and /session-close before
ending one.
-->

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free