In a Spec-Driven Development project the first file you write is not code. It is the rules. And it is not a methodological pose: the Spec Kit commands read that file before doing anything. When I launch from the planner, which in this case is Opencode with the GLM 5.3 LLM, /speckit.specify, the agent opens the constitution, checks what I have promised and adapts what it writes. If it does not exist, it makes it up. And what an agent makes up is not binding on anyone.
So I started there.
Nine principles, three that bite
The Cirineum constitution has nine principles. I wrote them on October 17 and it is still the document that has saved me the most. These are, summarized to one line:
- It is a local-use application, started from a single launcher on the user's machine and run from a web page. Everything runs on the local machine, with nothing to install on the system.
- A single httpd listener, on 127.0.0.1 and port 40127.
- Three interfaces: web, API and CLI.
- Single direction of dependency between layers. The interface does not know the database; the domain does not know HTTP.
- Traceability and no data destruction. Nothing is deleted silently; a member leaving is a change of status.
- Tests as a gate. A task without a test to back it is incomplete, not a style preference.
- Configuration without magic values. Every parameter has a default, a valid range and validation at startup.
- Data ownership and continuity. The cofradía can take all its data with it whenever it needs to.
- Personal data by design. Members' data is encrypted at rest and the key is kept in the operating system's store.
Three of the nine are going to cause trouble in this series, and it is worth flagging them now.
The second is the one that will cost me the most. It says the port is configurable but the scope is not: it never listens on 0.0.0.0. I wrote it because a configurable port with a free scope is an accidental exposure waiting to happen, and in post 5 we will see that complying with it forces you to document an exception with a name and a surname.
The sixth is the one that holds everything else up. It sounds like a textbook phrase until post 9 arrives and I have to measure cold start five times and prove behavioral parity between Windows 11 and Linux with captured fingerprints. That day the principle stops being pretty.
The ninth forced me to say out loud something uncomfortable: the password protects the interface, not the data; whoever has access to the file system does not need it.
What the constitution forces you to decide before you know
Here comes the first confession. I wrote it with Hermes as my pair coding partner and he came back with a list of ten points that were his judgment and not my decision. Two of them deserve telling.
The performance thresholds were his invention: two-second startup, a maximum search of 300 ms, one hundred milliseconds per receipt. He chose them loose relative to what was being measured in the proof of concept. I accepted them as they were, and that is exactly what you should not do with a constitution: a threshold you have not decided yourself binds you to nothing and yet it will sit there governing what the agent writes for months.
A month and a half later, the startup measurement came out at 718 ms on average and 764 ms in the worst case. It passed with margin. But that was luck, not method: if the threshold had been 900 ms, the feature would have been born non-compliant because of a figure an assistant picked.
The second point was more useful. He wrote that data import — from an export of another instance on another machine, say — replaces rather than merges, and that there is a single package format for backup, export and import. I had not said that. They are two decisions that, if improvised, destroy data, which is why they sit in principle eight and not in a plan. He got that one right, and I am writing it down because not everything an assistant proposes is noise.
The first commit is not code
With the constitution written, the first commit is still not code. It is the Spec Kit scaffolding, the agent prompts and two files that look minor and decide whether the project breaks or not.
The first is .gitignore. What it leaves out matters more than what it includes: the database and its journals, the data directory, the document store, keys and certificates, the .env, the logs, and the credentials that might one day turn up inside the agent's prompts folder. The reason is not aesthetic. This repository goes to a code server, and a cofradía's documentary archive cannot end up on a code server. If that line is not there from the first commit, the day you notice it you will already have the problem.
The second is .gitattributes, and this is the one almost nobody adds:
* text=auto eol=lf
*.sh text eol=lf
*.bat text eol=crlf
*.cmd text eol=crlf
*.ps1 text eol=crlf
*.png binary
*.exe binaryThe repository is used on Windows and Linux at the same time, and the Spec Kit scripts are bash. If Windows touches them and git leaves them with CRLF line endings, bash on Linux fails with errors that look like something else and you will spend an afternoon looking in the wrong place. With that rule, it does not happen.
Two more details from the first commit, and Hermes pointed out both at the time:
The agent prompts are versioned. It is not cosmetic: they are the ceremony. A new Orca worktree inherits the Spec Kit commands only if they are committed. If they are ignored, every worktree is born without commands and you have to reinstall the tool each time.
And worktrees live outside the repository. If Orca creates them inside, they show up as untracked directories and it is only a matter of time before you commit them by accident. It is decided before the first parallel feature, not after.
When the commit is made it leaves 158 files versioned in the repository. None of them is application code. All of that is written by someone else, later, and that is precisely the point.
The lesson
The constitution is not a welcome document. It is what makes an agent stop: when something does not fit a principle, the flow cannot continue without a written decision. And a written decision with a date, a reason and rejected alternatives is worth more than a hundred lines of good intentions.
To start managing the constitution I worked with my pair coding partner Hermes, laying out the idea for him and then iterating until we reached a coherent constitution. Here is the detail of the application idea I gave him to define the constitution:
This conversation is for you to help me make decisions and clarify concepts in the development of an application for managing a cofradía that I will │
implement in "/hdd2/configurations/feitam/workspaces/cirineumSDD". This application is called cirineum. I do not want you to do anything related to │
its implementation, only to clarify doubts so that I can make decisions. I will do everything myself with the help of pi and the SDD configuration. In│
particular I will ask you for help in clarifying the steps to manage the SDD. │
And I need you, in the cirineumSDD project located at /hdd2/configurations/feitam/workspaces/cirineumSDD, to help me define the content of all the SDD│
files based on SpecKit. I do not want you to change anything in the project, nothing, not a single file, unless I tell you to and confirm it through a│
question from you. I want to implement that project with SDD based on SpecKit and use different iterative agents to perform the different roles of │
project manager, team leader, programmers, functional tester, load tester, etc., all orchestrated with Orca and herdr according to a way of working │
that I will analyze with you (I think in session id 20261005_213612_ea6bc9). │
It is a project to learn and evaluate, but it is a real project to be run in production for an application that must run on Windows (at least Windows │
11) in a single executable that encapsulates everything to carry out the administration of a cofradía with all the maintenance of its members │
(registrations, removals, modifications, etc.), and it must also have a document management system for the cofradía with versions, tags, the ability │
to send to the printer, etc. And a feature for minutes or meeting notes, where they can be registered, viewed, filtered, searched, tagged, etc. And a │
historical log of events, etc., where each event can be recorded with its date, event name, detail, relationship with persisted documents (photos, │
docs, etc.) in the same tool. │
The application must have a web GUI to manage all this by calling localhost:40127. The application must have persistence such as sqlite3 or similar, │
and I think it should be implemented in the latest version of node with typescript and with express. It must be implemented in layers such as the │
httpd listener (apache or nginx, I prefer apache a priori), the view facade layer with the web routes, the view entity layer, the api layer, the dto │
entity layer, the dto persistence layer, the sqlite3 persistence, the document storage, etc. │
The application must have OpenAPI/Swagger for the api, and the REST api must be available on localhost:40123. In addition, it must have a CLI with all│
the functionality of the API. The CLI must be able to work on Windows and Linux with bash. The application, besides being able to run on Windows 11, │
must be able to run on a linux like this Ubuntu or similar. I understand that the application can be run by leaving a gui or console informing that │
Cirineum is running, and with the help message about running it in web mode by calling https://localhost:40127, by API https://localhost:40123 and by │
CLI with the basic commands. I prefer it to be a GUI. │
The app must have a system of constants or variables that can be changed, such as ports, pagination values in the web, etc. The application must have │
authentication by user and password plus a TOTP token managed internally by the application and that complies with the rules of a minimum 20-byte │
token. It must have configuration by authorization roles for each entity and function (create, remove, modify, delete, export, import data, etc.). │
Then in detail, little by little, we will go into the entities it manages and their attributes (fields) in persistence. │
With this I summarize the idea for you, and now let us go little by little seeing how I define the content of each SpecKit file starting with the │
constitution.md. A priori, from pi I have created the whole SpecKit structure but with the standard and/or empty content of its files. │
The constitution I am giving you — the most important thing to point out is that it was defined by me and by my pair coding partner Hermes, with the DeepSeek V4 Flash LLM that I use for any action, including this one, starting from a basic specification:
# Constitution of Cirineum
Project governance document. It fixes the invariants that no feature, plan or agent may contradict.
Everything else —what the product does (spec.md), how it is built (plan.md), what it is broken down
into (tasks.md)— is validated against this document.
Scope: application for the management of a cofradía, run on the user's machine, on Windows 11 and on
Linux. Working language, interface language and the language of this document: Spanish.
## Core principles
### I. Local appliance (NON-NEGOTIABLE)
- The whole stack —web server, application runtime, database and document store— is started and
supervised from a single launcher on the user's machine. Nothing runs outside that machine.
- Zero installation on the system: no runtime, database server or previous component. Zero
administrator permissions. Installation is per user.
- The user's data does NOT live in the installation directory. It survives any update and any
uninstallation.
- The launcher starts the components in order, checks that each one is ready before announcing that
the application is running, guarantees a single instance, collects the logs of the child processes
and terminates all of them when it closes, including any that are left orphaned.
- No component of the stack fails silently. If the web server or the core goes down, the application
reports it and does not remain in an apparently operational state.
- Any dependency on a remote service is forbidden: cloud, email sending, external identity,
analytics or telemetry. The application does not send data to third parties.
### II. Single surface and single port (NON-NEGOTIABLE)
- A single component listens for requests: Apache httpd, on 127.0.0.1 and port 40127. The port is
configurable; the scope (loopback) is not. It never listens on 0.0.0.0 or on a network interface.
- The web interface is served as static content and the REST API under /api/v1, on the SAME origin.
There is no CORS because there is no second origin.
- The API is described in OpenAPI, versioned, and that description is part of the deliverable.
- There is no TLS in v1: localhost is a secure context for browsers and local HTTPS would be
cosmetic. When a server mode exposed to the network exists, TLS becomes mandatory and this section
is amended before exposing anything.
### III. Surface parity (NON-NEGOTIABLE)
- Every feature available in the web interface is available through the API and through the CLI.
- The CLI is the same executable with subcommands: it works the same on Windows and on Linux and
does not depend on bash or on any system script interpreter.
- There is a single business logic behind the three surfaces. No surface implements its own rules or
accesses persistence directly.
- The commands that must work with the application stopped —start, stop, backup, restore— are the
only exception, they are identified as such and they are documented separately.
### IV. Single direction of dependency between layers
- The web interface does not know the database. The domain does not know HTTP. The API transfer
objects are not the persistence objects.
- The direction of dependencies is always inward: presentation → API → domain → persistence. A layer
never depends on another layer above it.
- The persistence layer does not leak its schema upwards: every data access goes through the domain.
- Skipping a layer requires a written and approved justification. It is not a style decision.
- The desktop launcher does not import domain modules and does not access persistence. It talks to
the core exclusively through its API. In the Electron window, context isolation is on and Node
integration is off: the interface does not execute privileged code or touch the user's file system.
### V. Traceability and no destruction (NON-NEGOTIABLE)
- Nothing is destroyed silently. Documents are kept with versions. A removal is a change of status,
not a deletion.
- Every relevant write is recorded in the log with what was done, when, and the actor when available.
- The history is product data, not a by-product: it is kept, exported and can be audited.
- Physical deletion, if it ever exists, is an exceptional, explicit and recorded operation.
### VI. Tests as a gate (NON-NEGOTIABLE)
- No task is considered finished without automated tests backing it. A behaviour change without a
test covering it is an incomplete task, not a style preference.
- Unit tests, API integration tests, contract tests against the OpenAPI specification, functional
interface tests and load tests are mandatory.
- Performance figures are measured in this project, with the declared load and their date, and they
are recorded. Figures published by third parties are not cited as if they were our own
measurements.
### VII. Configuration without magic values
- Every port, path, pagination limit and operational parameter is configurable, with a default value,
a valid range and validation at startup.
- Configuration is a first-class artifact: it is exported, imported and every parameter's effect is
documented.
- An invalid configuration prevents startup with a message that says exactly what is wrong and where.
The application does not start "halfway".
- Secrets do not travel in the configuration export unless there is an explicit, marked option.
### VIII. Data ownership and continuity
- The data belongs to the cofradía. It must be able to take all of it, at any time, without asking
anyone's permission.
- Three mechanisms, and they are different from each other: automatic, local backup with retention;
manual, portable export; and import.
- Import REPLACES the existing content. It does not merge. Merging is a different feature, with its
own rules, and it is not improvised.
- A single package format for the three uses, with a manifest declaring the format version, the
application version and the schema version, and a checksum per file.
- Import validates the whole package before touching anything and makes an automatic prior backup. An
interrupted import does not leave the system halfway.
### IX. Personal data by design (NON-NEGOTIABLE)
- Members' personal data is encrypted at rest.
- The key is kept in the operating system's store: DPAPI on Windows, keyring on Linux. The fallback is
a key file protected by a passphrase that the cofradía chooses and keeps, and that passphrase is part
of the delivery procedure.
- Export is the continuity mechanism: it includes the key in a restorable form protected by a
passphrase. Without the passphrase the package is inert; with it, it is restored on any machine.
- Minimization: only what the cofradía needs for its function is stored. What is not needed is not
requested and not stored.
- The real security limits are documented without adornment: the application password protects the
interface, not the data; whoever has access to the file system does not need it; and encryption
protects against copies of the data without the key, not against whoever controls the operating
system session.
## Technology standards
- Node as the application runtime, target line 24 with a fixed minimum patch. Strict TypeScript.
express as the HTTP application server. SQLite through node:sqlite, with FTS5. Apache httpd of the
current stable line as the only listener.
- Electron of the current stable line as the container of the launcher's desktop interface, and only
for that: window, dialogs, communication with the main process and process supervision. The
launcher is the parent process of the stack. The core does NOT run inside Electron: it runs on the
packaged Node runtime, which is what fixes line 24 and its minimum patch.
- Third-party dependencies: allowed if they are packaged inside the deliverable and appear on a
whitelist with their reason. The destination machine installs nothing, ever.
- No native npm modules: nothing to compile on the destination machine, neither per platform nor per
Node version. Platform-specific precompiled binaries —httpd, Electron and the Node runtime— are
pinned by version, travel inside the installer and are never compiled on the destination.
- Delivery: per-user installer. On Windows, without elevation. On Linux, the per-user equivalent —a
portable package with a desktop entry— and not .deb or .rpm, which would require root.
- Pin the line and the minimum patch, not an exact patch: security patches on the line must not force
an amendment of this document.
- node:sqlite is Release Candidate on line 24 from patch 24.15.0 (research.md R2). It is accepted as a
conscious decision. Before the first feature that persists data, its promotion to stable is
verified and, if it is not, this section is amended with the alternative and its reason.
- Delivery is a per-user installer that carries the whole stack: httpd, Electron, the Node runtime,
express, the compiled JavaScript and the OpenAPI description. The resulting size is measured and
recorded in every version; lightness is not promised.
- Packaging as a single executable (SEA) is not a requirement of any feature. It remains an optional
verification of the packaging feature and does not condition the design.
## Security
- There is no authentication of people and no role-based authorization in v1: local access grants
everything. Any future change to this decision forces an amendment of the constitution, because it
affects traceability, the log and data protection obligations.
- There is a single application password, whose purpose is to keep the application closed when nobody
is in front of the machine. It is not an identity and it is not an access control to the data.
- The password is stored with a slow, salted derivation function (Argon2id or scrypt). Never with a
fast hash such as SHA-256, never in clear, never reversible.
- The check is done in the application core, not in the interface. Without a valid session, the API
does not return data. The password cannot be an ornament on the entry screen.
- Session by HttpOnly cookie with strict SameSite and inactivity expiry. Rate limiting of failed
attempts and logging of them.
- Resetting the password requires access to the data directory. This is consistent with the real
limit declared above and it is documented as such.
- Encryption of personal data with AES-256-GCM. To search and guarantee uniqueness over encrypted data
a blind index is used, so that neither the search nor the uniqueness constraint requires decrypting
or exposing the clear value.
## Performance and scale
- No performance claim is written as an adjective. Every claim is a figure measured on the reference
machine, with the declared load and the date of the measurement.
- Reference load of the project: 5,000 members and 10,000 documents. Load tests run with that load and
the results are recorded.
- Provisional thresholds, to be verified and adjusted with the first formal measurement: cold start
under 2 seconds on the target machine; search over the reference load with a 99th percentile under
300 milliseconds; issuing a receipt as a PDF under 100 milliseconds; archiving a 2 MB document under
500 milliseconds.
- The reference scale does not change without first changing the load declared in this section.
## Coding standards
- Spanish in domain identifiers, file names, messages and comments. Comments explain the why, not the
what.
- Strict TypeScript, with no implicit any and no silent type escapes.
- One module, one responsibility, and a name that says which one.
- No new dependency without a written justification and approval.
- No dead code, and no undocumented special behaviour.
## Tests
- Unit: domain rules and utilities, without a database or network.
- Integration: the full API against the real database and the real document store.
- Contract: the implementation is checked against the OpenAPI specification, and the specification
against the implementation.
- Functional: web interface and CLI journeys, including the export and import flows and the restore
flows.
- Load: with the reference load declared above, measuring and recording figures.
- Tests run on the development machine with the same versions as the deliverable.
## Workflow and quality gates
- Ceremony order: constitution —once per repository— and, for each feature: specify, clarify, plan,
break down into tasks, analyze, check with a checklist, implement and converge.
- Mandatory gates before implementing: cross-artifact consistency analysis and the checklist, both
with no blocking findings.
- tasks.md is the source of truth for the work. A scope change is reflected there first, and then in
the code; never the other way round.
- One branch per feature. Nothing is merged without having passed the gates and without having been
reviewed by a person.
- Definition of "done": implemented, with tests backing it, with the contract updated if it touches
the API, with tasks.md marked, and without regressions in the rest of the suite.
## Rules for interacting with AI agents
- In this repository the planner is opencode, with an OpenAI-compatible provider; the executor is pi.
One planner and one runtime per repository: they are declared here and not changed halfway.
- The runtime is Orca. Its orchestration layer remains off: the person coordinates.
- pi executes the contract of plan.md and tasks.md and does not re-plan. If the contract is incomplete
or contradictory, pi stops and says so; it does not fill the gaps by inventing.
- An artifact has a single author. No agent writes spec.md, plan.md or tasks.md outside the role it is
assigned.
- No contradiction between artifacts is resolved by an agent's unilateral decision: the work stops and
it is reported.
- The agent does not touch anything outside the scope of the current task. It does not rename, move or
delete the user's data.
- No agent introduces network dependencies, cloud services or sending of data outside.
## Compliance
- The data processed is personal data of members of a cofradía. The cofradía is the controller; this
application is the tool.
- Applicable principles: specified purpose, minimization, accuracy, limitation of the storage period,
integrity and confidentiality.
- The application must SUPPORT the rights of access, rectification, erasure, restriction and
portability: to extract everything relating to a person, correct it and delete it where applicable,
without destroying the rest of the history.
- The application must be able to inventory what data it stores and for what purpose, to feed the
record of processing activities.
- There is no email sending, no analytics and no communication of data to third parties. There is no
processing outside the user's machine.
- The technical measures declared in the security section are what sustain this compliance and they
cannot be lowered without amending the constitution.
## Governance
- This constitution prevails over any other practice, preference or convention of the project. When it
clashes with something, either the constitution wins or the constitution is amended; no silent
exception is made.
- Amendment: it is proposed in writing with the reason, it is explicitly approved by the person
responsible for the project, and the affected artifacts are updated in the same move.
- Versioning of the document itself: MAJOR when a principle is removed or incompatibly redefined;
MINOR when a principle is added or a section is materially expanded; PATCH when only the wording is
clarified.
- Every plan must pass the constitution check. A plan that breaches it is not approved.
- Every exception to a principle is recorded with its date, its reason and its expiry date, and it
disappears when the reason disappears.
- Architectural decisions with lasting consequences are recorded as a decision document, with its
context, its alternatives and its justification.
- Registered amendments:
- 1.1.0 (2026-11-15) — Electron is admitted as the launcher container, scoped in the technology
article and in principle IV; the scope of "no native modules" is clarified; the node:sqlite
pending item is closed (Release Candidate since 24.15.0) and SEA is withdrawn as a requirement.
Reason: specification 001 requires a graphical window that owns the lifecycle, with Windows
11/Linux parity and no compilation on the destination (research.md R3,
docs/lista-blanca-dependencias.md).
**Version**: 1.1.0 | **Ratified**: 2026-10-17 | **Last Amended**: 2026-11-15
In the next post I write the specification of the first feature. With a rule that took me a while to understand: not a single technical decision goes in there.
---