Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/ISSUE_TEMPLATE/config.yml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
blank_issues_enabled: false
contact_links:
- name: Security vulnerability
url: https://github.com/hector-ae21/rup-flow/security/advisories/new
url: https://github.com/hector-ae21/rup-flow-docs/security/advisories/new
about: Report vulnerabilities and exposed credentials privately.

1 change: 1 addition & 0 deletions .markdownlint-cli2.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ config:
- sup
- figure
- figcaption
- a
- svg
globs:
- "**/*.md"
Expand Down
2 changes: 1 addition & 1 deletion CODE_OF_CONDUCT.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ private information, and conduct inappropriate in a professional setting.
## Enforcement

Report unacceptable behavior privately through the contact methods in the
[rup-flow security policy](https://github.com/hector-ae21/rup-flow/security/policy).
[security policy](SECURITY.md).
Project maintainers may remove, edit, or reject contributions and communication
that do not align with this code, and will respect the reporter's privacy.

Expand Down
8 changes: 3 additions & 5 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,12 +13,10 @@ procedure easier to follow, a statement more precise or a page easier to find.

## What to write

- Describe released behaviour of the free edition. Roadmap items are labelled as
such.
- Describe released behaviour of both editions. Roadmap items are labelled as such.
- Procedures state prerequisites, the result and how to recover.
- Describe rup-flow Pro at feature level only. A reader must not be able to
recreate a Pro capability from this site: no Pro commands, flags,
configuration keys, templates or step-by-step procedures.
- Mark everything that belongs to Pro: `edition: pro` and `since` in the front matter of a page,
the Pro tag in tables and steps.
- Examples contain no credentials or private data.

## Verify locally
Expand Down
21 changes: 11 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,10 @@

[![Documentation CI](https://img.shields.io/github/actions/workflow/status/hector-ae21/rup-flow-docs/pull-request.yml?branch=v0.x&logo=github&label=documentation%20CI)](https://github.com/hector-ae21/rup-flow-docs/actions/workflows/pull-request.yml)

Versioned documentation for [rup-flow](https://github.com/hector-ae21/rup-flow),
the skill that turns requirements into RUP documentation with your AI coding
agent. It documents the free edition completely and describes rup-flow Pro at
feature level.
Versioned documentation for rup-flow,
the skill that turns requirements into RUP documentation with any AI coding
agent. It documents the free edition and rup-flow Pro, and marks every page, row and step
that belongs to Pro.

Read it at <https://hector-ae21.github.io/rup-flow-docs/>. The site is versioned
by the free edition's `MAJOR.MINOR`; each approved publication also gets an
Expand Down Expand Up @@ -39,12 +39,13 @@ site with `.venv/bin/mkdocs serve`.

## Rules

- Document released behaviour. The free edition is documented completely.
- Describe Pro at feature level only. Never write content that would let someone
recreate a Pro capability: no Pro commands, flags, configuration keys,
templates or step-by-step procedures.
- The catalogue on the comparison page comes from `editions.json` of the free
repository. Update it there first, then here.
- Document released behaviour of both editions, in detail.
- Mark everything that belongs to Pro: `edition: pro` and `since` in the front matter of a
page, and the Pro tag in tables and steps. Pages without the mark describe the free edition.
- Never document behaviour that does not exist.
- Diagrams are PlantUML sources drawn in a light and a dark look; edit the source, not the SVG.
- The catalogue on the comparison page comes from `editions.json` of the skill (private
repository). Update it there first, then here.
- Examples contain no real credentials or private data.

## Versions
Expand Down
10 changes: 3 additions & 7 deletions SECURITY.md
Original file line number Diff line number Diff line change
@@ -1,18 +1,14 @@
# Security policy

This repository holds documentation sources and tooling. It processes no user
data and publishes no secrets.
This repository holds documentation sources and tooling. It processes no user data and publishes no secrets.

## Reporting a vulnerability

Use GitHub private vulnerability reporting: **Security → Report a vulnerability**
on this repository, or on
[hector-ae21/rup-flow](https://github.com/hector-ae21/rup-flow/security/advisories/new)
for the skill itself. Do not open a public issue for a vulnerability or an
exposed credential.
Use GitHub private vulnerability reporting: **Security → Report a vulnerability** on this repository. It reaches the maintainer for the documentation and for the skill. Do not open a public issue for a vulnerability or an exposed credential.

## Scope

- Content that suggests an unsafe practice.
- A credential or private data committed by mistake.
- A vulnerability in the build or publication workflows.
- A vulnerability in the rup-flow skill or its packages.
18 changes: 17 additions & 1 deletion cspell.json
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,22 @@
"lms",
"Lifecycles",
"nodesep",
"ranksep"
"ranksep",
"nrup",
"usecases",
"opencode",
"clinerules",
"kilocode",
"junie",
"amazonq",
"grayscale",
"rrggbb",
"ddark",
"windsurf",
"cline",
"roo",
"aider",
"mjs",
"ifdef"
]
}
67 changes: 67 additions & 0 deletions docs/architecture/behavior.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
---
title: Runtime behaviour
description: What happens, step by step, when the agent adds a use case, renders diagrams and starts the CLI.
---

# Runtime behaviour

Three scenarios show how the pieces cooperate. Each one is a rule you can rely on.

## Adding a use case

<div class="rup-diagram" role="region" aria-label="Scrollable UML sequence of adding a use case" tabindex="0" markdown>

![Sequence: the person asks for a use case, the agent runs new use-case, the CLI picks the next identifier, writes the missing files and refreshes the index, the agent fills the card and runs check, and reports what it did](../assets/diagrams/light/new-use-case.svg#only-light)
![Sequence: the person asks for a use case, the agent runs new use-case, the CLI picks the next identifier, writes the missing files and refreshes the index, the agent fills the card and runs check, and reports what it did](../assets/diagrams/dark/new-use-case.svg#only-dark)

</div>

1. The person states the use case in plain language.
2. The agent runs `new use-case` with what it knows: actor, package, goal.
3. The CLI chooses the next free identifier by reading the existing cards, writes only the
files that do not exist yet, and regenerates the index from the cards.
4. The agent fills the card from what the person said. Whatever the person did not say
becomes an open question.
5. The agent runs `check` and reports the files, the open questions and what was not
checked.

Two properties follow. Running the command twice never overwrites work, because existing
files are skipped. And the index is always derived from the cards, never edited by hand.

## Rendering diagrams

<div class="rup-diagram" role="region" aria-label="Scrollable UML sequence of rendering diagrams" tabindex="0" markdown>

![Sequence: the CLI finds every source, sends each one that is not up to date to the PlantUML server, writes the SVG next to the source on success and lists the diagram as failed on error, then records the render state and exits with code 1 if anything failed](../assets/diagrams/light/render.svg#only-light)
![Sequence: the CLI finds every source, sends each one that is not up to date to the PlantUML server, writes the SVG next to the source on success and lists the diagram as failed on error, then records the render state and exits with code 1 if anything failed](../assets/diagrams/dark/render.svg#only-dark)

</div>

- A diagram is up to date when its SVG is newer than its source; `--force` redraws
everything, and a change of palette does so automatically.
- A failure of one diagram never stops the others. The report lists what was drawn,
what was skipped and what failed, and the exit code is `1` when anything failed.
- The SVG is written to a temporary file and moved into place, so an interrupted run
never leaves half an image.

## Starting the CLI

<div class="rup-diagram" role="region" aria-label="Scrollable UML activity of how the CLI chooses its edition" tabindex="0" markdown>

![Activity: the CLI starts and checks whether the Pro entry exists; if so it loads the Pro extension; if not it is the free edition and stops with a Pro notice when the command or flag needs Pro; either way it writes the report](../assets/diagrams/light/edition-loading.svg#only-light)
![Activity: the CLI starts and checks whether the Pro entry exists; if so it loads the Pro extension; if not it is the free edition and stops with a Pro notice when the command or flag needs Pro; either way it writes the report](../assets/diagrams/dark/edition-loading.svg#only-dark)

</div>

The edition is decided once, at start, by one file. A command that needs Pro never
half-runs in the free edition: it stops before doing any work and says which part is
missing.

## The report

Every command ends with a report: a title, then labelled values and lists. The same shape
is used by all commands so an agent can read any of them the same way.

## Related

[Structure](structure.md) · [Editions and the extension point](editions.md)
85 changes: 85 additions & 0 deletions docs/architecture/decisions.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
---
title: Quality and decisions
description: The qualities the rup-flow design protects and the decisions behind it, with the reasons and the alternatives that were rejected.
---

# Quality and decisions

## Qualities

| Quality | How it is protected |
| --- | --- |
| Portability | The skill follows the open Agent Skills format; adapters isolate each agent; the CLI needs only Node.js |
| Honesty | Provenance marks, the rule against inventing content, open questions, and a CLI that refuses what the edition lacks |
| Repeatability | Commands skip what exists, derive indexes from the cards, and record the render state |
| Safety | Writes only inside chosen folders; local, sandboxed rendering; no network calls of its own |
| Maintainability | One reason to change per module; a catalogue and validation that stop the editions drifting |
| Compatibility | One CLI and one skill structure for both editions, so a project moves from free to Pro without renaming |

## Decisions

Each decision states the context, the choice and what it costs.

### D-01 A skill plus a CLI, not a skill alone

**Context.** An agent writes good prose and bad boilerplate: it renumbers identifiers,
forgets to refresh an index, draws diagrams it cannot see.
**Decision.** Mechanical work is deterministic code behind a command line; judgement stays
with the agent.
**Cost.** The agent must be able to run a command; an agent that cannot, writes documents
without rendering or checking and must say so.

### D-02 No runtime dependencies

**Context.** The skill is unzipped into any folder on any machine.
**Decision.** The CLI uses only the Node.js standard library.
**Cost.** Small utilities are written in the project instead of imported.

### D-03 PlantUML in a local container, not a hosted service

**Context.** Diagrams describe private systems.
**Decision.** Rendering goes to a container on the loopback interface, with a sandboxed
profile.
**Cost.** Docker is needed to draw; without it the sources are still written and can be
drawn later.

### D-04 One CLI, two editions, selected by a file

**Context.** Forking the code for a paid edition doubles every fix.
**Decision.** The free CLI loads an extension when it finds `scripts/pro/index.mjs`; the Pro
package is the free skill with an overlay.
**Cost.** The free tree must expose clean extension points and stay free of Pro code, which
validation enforces.

### D-05 Refuse, do not degrade

**Context.** A free edition that quietly produces a weaker version of a Pro artifact would
mislead.
**Decision.** Anything outside the edition stops with a message that names Pro, or is
counted and listed; the skill tells the agent not to improvise it.
**Cost.** Some requests end earlier than a user expects, which is the point.

### D-06 Numbered folders that never change

**Context.** Users move from free to Pro.
**Decision.** Both editions use the same discipline folders; Pro fills the rest.
**Cost.** The free tree shows folders that Pro uses and the free edition leaves empty or
absent.

### D-07 Light and dark diagrams are two files

**Context.** One SVG cannot be readable on both a white and a dark page.
**Decision.** Documentation diagrams are drawn twice from one source with two palettes and
the page shows the one that matches its theme.
**Cost.** Twice the files, checked as a pair by the build.

### D-08 Instruction files for agents without skills

**Context.** Many agents read a rules file instead of Agent Skills.
**Decision.** A command writes a small, delimited block into the file each tool reads and
replaces only that block.
**Cost.** The list of targets follows each tool's conventions and needs maintenance.

## Related

[Structure](structure.md) · [Delivery and branches](delivery.md)
67 changes: 46 additions & 21 deletions docs/architecture/delivery.md
Original file line number Diff line number Diff line change
@@ -1,39 +1,64 @@
---
title: Delivery and branches
description: How rup-flow is released, which branches exist and how this documentation is published.
description: How rup-flow is branched, versioned and released, and how this documentation is published.
---

# Delivery and branches

## Repository
## One repository, two branches

| Branch | What it is | Who writes it |
| --- | --- | --- |
| `main` | Source of truth; protected, changes arrive through pull requests with `CI complete` | Pull requests |
| `claude-plugin` | The plugin payload the marketplace and the directory read | The release workflow, on each `vX.Y.Z` tag |
| `docs-assets` | The README screenshot and the PNG icon | The maintainer, when images change |
The source lives in one private repository with two long-lived branches. The packages built
from them are what is published; the source is not.

The plugin tree contains no binary files; images that need one live on
`docs-assets` and are linked by address.
<div class="rup-diagram" role="region" aria-label="Scrollable UML diagram of the branch and release model" tabindex="0" markdown>

## Release
![The main branch holds the free edition and is merged into the pro branch; tags on each branch trigger release workflows that build the versioned free and Pro packages; the public documentation site describes both](../assets/diagrams/light/branch-model.svg#only-light)
![The main branch holds the free edition and is merged into the pro branch; tags on each branch trigger release workflows that build the versioned free and Pro packages; the public documentation site describes both](../assets/diagrams/dark/branch-model.svg#only-dark)

1. Move the `Unreleased` entries of the changelog to a new version section.
2. Bump the version in `package.json`, the plugin manifest and `SKILL.md`.
3. Merge to `main`, then tag `vX.Y.Z`.
4. The release workflow validates and tests, publishes `rup-flow-skill.zip` on the
GitHub release and regenerates the `claude-plugin` branch.
</div>

## Continuous integration
| Branch | Holds | Tag | Package |
| --- | --- | --- | --- |
| `main` | The free edition | `vMAJOR.MINOR.PATCH` | `rup-flow-free-<version>.zip` |
| `pro` | `main` plus the `pro/` folder: overlay, build, tests, license | `pro-vMAJOR.MINOR.PATCH` | `rup-flow-pro-<version>.zip` |

`main` is complete and never contains anything from Pro. After a change lands in `main` it is
merged into `pro`, so the Pro build always contains a known free version, and the Pro package
states it. Both branches only take changes through pull requests with `CI complete`.

## From change to package

<div class="rup-diagram" role="region" aria-label="Scrollable UML diagram of the release pipeline" tabindex="0" markdown>

![A pull request runs CI; once CI is complete it is merged; a tag with the version bumped and the changelog written starts the release workflow, which checks, builds and packages; the GitHub release carries the versioned ZIP, which is uploaded to the marketplace listing](../assets/diagrams/light/release-pipeline.svg#only-light)
![A pull request runs CI; once CI is complete it is merged; a tag with the version bumped and the changelog written starts the release workflow, which checks, builds and packages; the GitHub release carries the versioned ZIP, which is uploaded to the marketplace listing](../assets/diagrams/dark/release-pipeline.svg#only-dark)

</div>

| Job | Checks |
| --- | --- |
| Validate | Skill format, manifests, links, no binaries, no Pro templates |
| Test | The CLI test suite on Linux and Windows with Node.js 18 and 22 |
| Validate | Skill format, links, no sensitive-looking names, no Pro templates in the free tree |
| Test | The CLI suite on Linux and Windows with Node.js 18 and 22 |
| Render | `init`, `new use-case`, `render` and `check` against a real PlantUML server |
| Pro tests | The built Pro skill: every command, the explorer, the example project and the package |

The release workflow checks that the tag equals the version in the files, runs the tests,
builds the package and attaches it to the GitHub release with the changelog section as its
notes. A release is never overwritten.

## Version identity

A package names its version in three places that must agree: the file name, `SKILL.md`
metadata and the output of `RUP version`. Pro also names the free version it contains. See
[Versioning and URLs](../releases/versioning.md).

## This documentation

The site is built with MkDocs Material and published with Mike. The version
selector uses the free edition's `MAJOR.MINOR`. Each approved publication gets an
immutable tag and a GitHub release. See [Versioning and URLs](../releases/versioning.md).
The site is built with MkDocs Material and published with Mike, from the public
`rup-flow-docs` repository. The version selector uses the free edition's `MAJOR.MINOR`, and
Pro is documented on the line of the free version it contains. Each approved publication gets
an immutable tag and a GitHub release.

## Related

[Editions and the extension point](editions.md) · [Quality and decisions](decisions.md)
Loading
Loading