Before writing the specification I did something the flow did not require: I created the branch by hand.
git switch -c 001-arranque-y-servicioThe constitution says one branch per feature, and the Spec Kit git extension was not installed, so I created the branch myself. That let me discover, a minute later, that the branch is useless for naming the specification.
The branch does not name the directory
I launched, from the planner in Opencode with GLM 5.3 LLM, /speckit.specify with a description of the desired behaviour and I expected the directory to be named after the branch. It does not work that way. The command's own prompt says it in so many words: the branch name does not dictate the name of the specification directory. The name is derived from the description text, extracting two or four significant words and putting them in kebab-case.
Practical consequence: if you pass it only the long description, the result is unpredictable but legitimate. You may get 001-arranque-servicio, 001-servicio-arranque or 001-ejecucion-cirineum. Any of them is fine. It simply will not match the branch.
The way to force it without contaminating the specification is to add a separate instruction at the end of the prompt: "use the short name: arranque-y-servicio". It is a process instruction, not an observable behaviour, and the command itself separates the two things. The number 001 is assigned by scanning the specifications directory; as none existed, it came out 001.
And if it goes wrong, the cost of the mistake is ten seconds: nothing is born pointing at that path except .specify/feature.json, so you fix it by moving the directory and editing the pointer. I talk about that file in the post:
What came out
The specification of feature 001 has four user stories, eighteen functional requirements, six success criteria and a pile of scenarios. Twenty-two kilobytes. Each story comes with three things that are what make it useful:
- a priority, with a sentence explaining why that priority and not another;
- an independent test, that is, how that story alone is proven, without the others;
- acceptance scenarios in given / when / then format.
All of this, as always, was done with the help of my pair coding partner Hermes.
The four stories, in the order they ended up in:
P1, truthful startup and local service available. The person runs Cirineum, the system brings everything up and announces "running" only when it really responds. The page opens in the machine's browser and is not reachable from any other machine on the network.
P2, clean shutdown, zero orphan processes. It is closed through the usual routes and not a single live process remains.
P3, single instance guaranteed. If one is already running, the second run is rejected with a clear message and the original keeps working.
P4, reported startup failure, no half-done state. If something fails, the reason is stated and nothing is left apparently operational.
That order is not accidental and I did not choose it at the end: I chose it while writing. P1 is the minimum that can be delivered and used. The other three can be tested separately on top of it. That is what "independent test" means, and it is what later allows implementing in phases instead of having forty-eight tasks open at once.
Eighteen requirements and none of them talks about technology
Here is the discipline that cost me the most. In spec.md Node does not appear. Apache does not appear. httpd.conf does not appear, nor SIGTERM, nor Electron, nor a single architecture decision. The only technical mention in the whole document is port 40127 inside a scenario, and it is there because it is observable behaviour: the user sees an address.
A few requirements, so you can see the level of precision:
- FR-002: the service point listens exclusively on the local interface 127.0.0.1.
- FR-004: the system actually checks, before announcing that it is running, that the service point responds.
- FR-008: a second run while one is running is rejected.
- FR-011: the full startup and shutdown cycle works without administrator permissions.
- FR-014: the behaviour is equivalent on Windows 11 and Linux.
- FR-018: that equivalence is verified on three explicit bases, not on an impression.
Look at what they say and what they do not say. "Without administrator permissions" is a requirement; "do not install a Windows service" is a solution. "Equivalent on Windows and Linux" is a requirement; "use Electron" is a solution. Every time I wrote a solution, I rewrote it as behaviour. If the design goes in here, the plan no longer decides anything: it just obeys.
The six success criteria follow the same rule, and they are uncomfortable on purpose:
- SC-001: cold startup is available in under two seconds.
- SC-002: one hundred percent of the "running" announcements match a service that responds.
- SC-003: after each shutdown, zero live related processes.
- SC-004: one hundred percent of second runs are rejected.
- SC-005: one hundred percent of the provoked failures are reported with the exact message.
- SC-006: zero percent of accesses from another machine on the network succeed.
A criterion that says "one hundred percent" or "zero percent" is a promise that can be broken. One that says "startup is fast" cannot even be checked. The difference between the two is post 9 of this series, where it is time to measure them for real.
It did not come out right the first time
Two "iterative evolution" commits before moving on to the plan. The first version had gaps: requirements that overlapped, scenarios that did not say what success was, and a thing or two that was design in disguise. What those two commits did was basically the same as what I do when writing any text: cut half of it and make the other half precise.
I do not know anyone who writes a good specification in one pass, and I distrust anyone who says they do. What can be demanded is that the second pass be reviewed by someone other than the author, and there the reviewer worked.
The file of this specification, located in specs/001-arranque-y-servicio, is:
# Feature specification: Startup and service
**Feature Branch**: `001-arranque-y-servicio`
**Created**: 2026-10-17
**Status**: Implemented (2026-11-15)
**Input**: User description: "When Cirineum is run, the machine is left serving the application at http://localhost:40127 and when it is closed no process remains alive. Acceptance criteria: it listens only on 127.0.0.1:40127; the page responds; 'running' is not announced until the port responds; on close no orphan processes remain; a second simultaneous run is rejected; if the server does not start, this is reported and it is not left half done."
## Clarifications
### Session 2026-11-10
- Q: What must the system actually check before announcing that the application is "running"? → A: Port + core: the service point responds and the application core confirms it is operational (an end-to-end check, not just the port).
- Q: When the service point stops responding with the application running, what must the system do after notifying it? → A: Shut everything down: it notifies the reason, stops the components, leaves zero live processes and terminates after a visible notice.
- Q: Which concrete mechanisms count as "exit from the application itself" when closing Cirineum? → A: The exit control of the launcher window and a shutdown action in the web interface; closing the browser tab does not shut down.
- Q: What role does the launcher window play while the application is "running"? → A: Permanent control window (status, open in browser, stop); closing it shuts down; no system tray in v1.
- Q: Does this feature also include the CLI subcommands (start/stop) that the constitution requires to work with the application stopped? → A: No: separate feature; this spec covers only the graphical launcher and its diagnostic console route.
## User scenarios and tests *(mandatory)*
### User story 1 - Truthful startup and local service available (Priority: P1)
A person in the cofradía runs Cirineum on their machine. The system brings up in the background
every component needed to serve the application and actually checks that the service point
responds and that the application core is operational. Only then does it announce that the
application is "running", indicating the
address where to use it. The page opens correctly in a browser on that same machine, and the
application is not reachable from any other machine on the network: it is a local appliance, not
an exposed server.
**Why this priority**: without a working startup and a truthful announcement, there is no
application to use and no trust in the rest of the behaviours. It is the user's first contact with
the product.
**Independent test**: run Cirineum, wait for the "running" announcement, open the announced
address in a browser on the same machine (the page must respond) and check from another machine
on the same network that the address does not respond.
**Acceptance scenarios**:
1. **Given** a machine with Cirineum installed per user and no instance running, **when** Cirineum
is run, **then** the system goes through a visible startup state and announces "running" only
after the service point really responds on 127.0.0.1:40127 and the application core confirms it
is operational.
2. **Given** the "running" announcement has been issued, **when** the address is accessed with a
browser on the same machine at http://localhost:40127, **then** the application's main page
responds correctly.
3. **Given** the application running, **when** another machine on the same network tries to access
the service address, **then** no response is obtained at all: the service only listens on the
local interface (127.0.0.1).
---
### User story 2 - Clean shutdown, zero orphan processes (Priority: P2)
The user closes Cirineum through any of its usual routes (the exit control of the launcher window,
the shutdown action in the web interface, closing the launcher window or interrupting from the
console; closing the browser tab is not a shutdown route). The system stops every component it
brought up, in order, and leaves the machine exactly as it was: no process related to Cirineum
remains alive. The user needs to know nothing about process management to avoid leaving "things
running".
**Why this priority**: it is the counterpart of startup and the basis of trust in a local appliance
application: what is switched on is switched off completely. It also avoids port conflicts and
resource consumption in later runs.
**Independent test**: with Cirineum running, close it through each usual route and check, with the
operating system's own tools, that no live process related to the application remains.
**Acceptance scenarios**:
1. **Given** an instance of Cirineum running, **when** the user exits from the launcher interface,
**then** every started component stops and no live process related to the application remains.
2. **Given** an instance of Cirineum running, **when** the user closes the launcher window directly,
**then** the result is the same: zero live processes.
3. **Given** an instance started from a console, **when** its execution is interrupted from the
console, **then** the result is the same: zero live processes.
4. **Given** an instance of Cirineum running and the application open in a browser on the same
machine, **when** the user uses the shutdown action in the web interface, **then** the result is
the same: zero live processes.
---
### User story 3 - Single instance guaranteed (Priority: P3)
While Cirineum is running, an additional launch (out of distraction, out of doubt, from a repeated
double click) does not start a second service and does not corrupt the state of the active
instance: the system rejects the second run with a clear message saying that an instance is already
running and how to reach it.
**Why this priority**: it guarantees that the machine serves exactly one application with a single
service point, avoiding undefined behaviour, port conflicts and user confusion. It depends on
startup working (H1), but it is independent of shutdown (H2).
**Independent test**: with an instance running, run Cirineum a second time and check that it is
rejected with a clear message, that no second service point appears and that the first instance
keeps working normally.
**Acceptance scenarios**:
1. **Given** an instance of Cirineum running, **when** Cirineum is run a second time on the same
machine, **then** the second run reports with a clear message that an instance is already running
(indicating the address to use it) and terminates without bringing up a second service.
2. **Given** that the second run was rejected, **when** the original instance is used, **then** it
keeps responding normally at its address, having been left unaffected.
---
### User story 4 - Reported startup failure, no half-done state (Priority: P4)
If for any reason the server does not manage to start —the port is taken by another application, a
component fails or the configuration is invalid— Cirineum does not pretend: it reports the reason
with a concrete message (what failed and, if it is a configuration problem, which parameter is
wrong), it never announces "running" and it finishes leaving the machine clean, with no components
half started and no live processes.
**Why this priority**: a silent failure or an apparently operational state would destroy trust in
the application and leave the user not knowing what to do. It is the last of the lifecycle
guarantees, but without it the other three lie.
**Independent test**: provoke each cause of failure (occupy the port with another application,
introduce an invalid configuration) and check that Cirineum reports the concrete reason, does not
announce "running" and leaves no live process.
**Acceptance scenarios**:
1. **Given** that port 40127 is taken by another application unrelated to Cirineum, **when**
Cirineum is run, **then** it specifically reports that it could not serve on the port (port
taken), does not announce "running" and terminates without leaving any live process.
2. **Given** an invalid configuration (for example, a port outside the valid range), **when**
Cirineum is run, **then** startup is blocked with a message that states exactly which parameter
is wrong and where, and no live process remains.
3. **Given** that a component of the stack fails during startup, **when** the launcher detects it,
**then** it stops the rest of the already started components, reports the reason and leaves no
live process.
---
### Edge cases
- What happens when the default port is taken by another application unrelated to Cirineum?
Startup is reported as a specific failure (port taken) without ever announcing "running" or
leaving anything alive (H4, scenario 1).
- What happens when the port is taken precisely by another instance of Cirineum? The second run is
treated as a duplicate instance, with the single-instance message (H3), not as a generic port
failure.
- What happens if the launcher is forcibly killed with the components running? The system must
still terminate every component; if the launcher itself dies violently, the next run must reach a
clean state or clearly report what prevents startup.
- What happens if the service responds and then stops doing so while the application is running?
The system notifies it with the reason, shuts everything down (zero live processes) and does not
remain in an apparently operational state; there are no silent failures.
- What happens on a power loss with the application running? The next run must be able to complete
a clean startup without manual intervention.
- What happens if it is closed and started again immediately? Startup must complete without user
intervention and without being left half done.
- What happens if the port configuration is changed while an instance is running? The running
instance is not affected; the new value applies on the next run.
## Requirements *(mandatory)*
### Functional requirements
- **FR-001**: When Cirineum is run on the user's machine, the system MUST bring up a single service
point that serves the application's web interface at http://localhost:40127.
- **FR-002**: The service point MUST listen exclusively on the local interface 127.0.0.1 and MUST
NOT be reachable from any other machine on the network (never on 0.0.0.0 nor on an external
network interface).
- **FR-003**: The port of the service point MUST be configurable, with 40127 as the default value
and a defined valid range; a configuration with an invalid or out-of-range port MUST prevent
startup with a message that states exactly which parameter is wrong and where.
- **FR-004**: The system MUST actually check, before announcing that the application is "running",
that the service point responds AND that the application core is operational (an end-to-end
check, not only that the port answers); the announcement cannot be issued merely because the
components were launched.
- **FR-005**: Next to the "running" announcement, the system MUST show the web address where to use
the application and offer shutdown from the launcher window itself, which MUST remain open as a
control panel (status, open in browser, stop) while the application is running; closing that
window means shutting the application down.
- **FR-006**: Once the "running" announcement has been issued, the main page MUST respond, when
accessed from a browser on the same machine at the announced address, with an HTTP 200 result
and the content of the application's main page, with no error page from the proxy or from the
server and without requesting authentication.
- **FR-007**: When the application is closed through any of its usual routes —the exit control of
the launcher window, a shutdown action in the web interface, closing the launcher window or
interrupting from the console—, the system MUST stop every component it brought up and MUST NOT
leave any live process on the machine. Closing the browser tab is NOT a shutdown route and does
not affect the execution.
- **FR-008**: A second run of Cirineum while one is already running on the same machine MUST be
rejected: it MUST NOT bring up a second service point, it MUST report with a clear message that
an instance is already running and how to access it, and it MUST terminate without disturbing the
active instance.
- **FR-009**: If the service point does not manage to start (port already taken, failing component
or invalid configuration), the system MUST report the reason with a specific message, MUST NOT
announce "running" and MUST finish without leaving half started components or live processes.
- **FR-010**: If the service point stops responding while the application is running, the system
MUST notify it with the reason and then MUST stop every component, leave zero live processes and
finish after a visible notice: it MUST NOT remain in an apparently operational state or be left
half done.
- **FR-011**: The full startup and shutdown cycle MUST work without administrator permissions and
without installing anything additional on the system, both on Windows 11 and on Linux.
- **FR-012**: The system MUST keep a log of the startup, preparation, shutdown and error activity
of its components, with date and time and the reason in case of error, as consultable diagnostic
material. Consultable means readable without special tools, such as text files in the per-user
diagnostic directory, one per run, with the location and the way to consult them documented for
the user.
- **FR-013**: The single-instance and clean-startup guarantee MUST also hold after an abrupt
shutdown (forced termination of the launcher or power loss): the next run MUST reach a clean
state or clearly report what prevents startup. The check that a registered instance is still
alive MUST be based on the process identity —number, start time and executable—, not only on the
number, so as not to mistake a PID reused by another process for the registered instance.
- **FR-014**: The behaviour of startup, announcement, rejection of a second instance, drop
notification and shutdown MUST be equivalent on Windows 11 and on Linux.
- **FR-015**: If the user closes the launcher during the startup phase, before the "running"
announcement is issued, the system MUST abort startup, stop the components already launched and
terminate with zero live processes, without ever issuing the announcement.
- **FR-016**: Two or more launches started almost simultaneously MUST resolve to exactly one
instance: one progresses and the others are rejected with the single-instance message of FR-008,
with the race producing neither two service points nor an inconsistent intermediate state.
- **FR-017**: After the drop notice of FR-010, the system MUST stop the components in reverse order
to startup. The notice with the reason MUST be shown in the control panel window, in an error
state, without opening additional windows, and MUST remain visible until the user closes that
window; on closing it no window or process of the application MUST remain.
- **FR-018**: The equivalence of FR-014 is verified on three explicit bases: the same visible
messages in text and purpose, the same observable results (announcement, rejection, shutdown) and
the same count of live processes. Presentation differences inherent to the operating system
—dialogs, paths, process names— do NOT count as divergence.
### Key entities *(include if the feature involves data)*
- **Run instance**: each bringing-up of Cirineum on a machine. Attributes: unique identification
within the machine, state (starting, running, stopping, stopped), start time and effective
service address. Transitions: starting → running only after satisfying FR-004; starting →
stopped by failure (FR-009) or by abort (FR-015); running → stopping → stopped by any of the
routes of FR-007, by service drop (FR-010) or by abrupt shutdown (FR-013, which is resolved on
the next run). Rule: at most one running instance per machine.
- **Local service point**: the address where the web interface is served (by default
127.0.0.1:40127). Attributes: port (configurable, with a default value and a valid range) and
scope (only the machine itself; not configurable).
- **Run log**: sequence of startup, preparation, announcement, shutdown and error events, with date
and time, affected component and reason. It is diagnostic material, not business data.
## Success criteria *(mandatory)*
### Measurable outcomes
- **SC-001**: Cold startup is available —from the run until the page responds at the announced
address— in under 2 seconds on the reference machine —identified and recorded, with date and
load, in `specs/001-arranque-y-servicio/mediciones.md`, section SC-001— (provisional threshold of
the constitution, to be verified with the first formal measurement).
- **SC-002**: 100% of the "running" announcements match a service that really responds at the
announced address: zero false announcements in the test battery (defined as the V1–V6 routes of
`quickstart.md` plus the automated functional test suite).
- **SC-003**: After each shutdown through the usual routes, the number of live processes related to
the application on the machine is 0 (verifiable with the operating system's process tools).
- **SC-004**: 100% of the second runs attempted during the test battery are rejected with a clear
message, without affecting the running instance.
- **SC-005**: 100% of the startup failures provoked in the test battery —which covers at least a
port taken by an unrelated application, an invalid configuration and a component failure— produce
a message that identifies the concrete reason and terminate with 0 live processes and without a
"running" announcement.
- **SC-006**: From another machine on the same network, 0% of the access attempts to the service
address obtain a response.
## Out of scope for this feature (v1)
The following is explicitly declared out of scope. It is not a wish list: it is the boundary of
what the verification of this feature is going to require.
- **Failure of the orphan cleanup itself** (a registered PID that does not terminate, permissions
that prevent deleting the state file): the system records the error and stops startup reporting
the reason. No automatic retry nor escalation to operating system mechanisms is specified.
- **A second drop during the recovery itself**: the resulting state is treated as an abrupt
shutdown on the next run; there is no additional guarantee about the intermediate point.
- **Corrupt or unreadable state file**: it is treated as an orphan —its content is archived in the
diagnostic log when possible and it is rebuilt—, with no repair format of its own.
- **Minimizing the control panel window**: it keeps the same controls and the same state; no
special behaviour on minimizing or restoring is specified.
- **Lifecycle CLI subcommands** (start, stop with the application stopped): they remain a separate
feature over the same domain logic. The debt of principle III of the constitution (surface
parity) is closed with that feature, not with this one.
- **Installation and packaging** (per-user installer, packaged binaries, single executable): the
anchor points are prepared, but the deliverable belongs to the packaging feature.
- **Linux desktops unable to show a graphical window**: the target desktops are validated in the
platform verification of FR-011 and FR-014. A desktop that cannot show the launcher window is not
a supported mode in v1 and no interface-less alternative is offered.
## Assumptions
- The CLI subcommands to operate with the application stopped (start, stop) required by principle
III of the constitution remain outside this feature and will be specified separately over the
same domain logic; this feature covers the launcher and only admits the console as a diagnostic
alternative.
- Lifecycle control (start, see the status, close) is offered through a graphical launcher window,
according to the preference declared for Cirineum; a console route is admitted as a diagnostic
alternative. The launcher window remains open as a control panel while the application is
running; there is no system tray in v1 and closing it means shutting down.
- "localhost:40127" is assimilated to 127.0.0.1:40127 (local interface).
- The valid range of the configurable port corresponds to non-privileged ports available on the
system; the concrete range is fixed in the planning phase.
- After an abrupt shutdown (power loss or forced termination), the next run must be able to reach a
clean state without manual intervention from the user.
- Application password authentication and session management are not part of this feature: this
feature ends when the service responds and "running" is announced.
- The running supervision detects that the service point stops responding, notifies it and applies
the full stop of components (FR-010); automatic restart of failed components is out of scope for
v1.
Notice the status: it says "Implemented", which means this specification has gone through every Spec Kit stage, implementation included. That makes sense: everything must have identified states, tasks and checks so you know whether to keep coding or not until the acceptance scenarios are met.
The lesson
The specification describes what is seen from outside: what the system does, under what conditions, and how you know it did it. Everything else is surplus. And when in doubt, the test is simple: if you delete that sentence, does the observable behaviour change? If it does not change, it is design and it goes in the plan.
Writing the specification is meticulous work in which you can lean on your pair coding partner and iterate improvements on the definition until it is closed.
In the next post, five questions. Four, actually. The first one looks trivial and decides half the feature.