RepoFoundry/docs/uc-002/uc.md

Start the script as a global command

Metadata

Key	Value
ID	UC-002
CrossReference	UCD-001, US-001, SA-001, BC-001

Version History

Date	Status	Author	Reviewer	Change	Commit
2026-10-07	Proposed	Jens Tirsvad Nielsen	S02	Initial version	pending

---

Format: Fully Dressed

Fully Dressed

• Scope: RepoFoundry (create-project.sh)
• Level: user-goal
• Primary Actor: Maintainer (S01 or S02; one person holds both roles for now)
• Stakeholders and Interests:
  • S01 — the script is started by name from any folder, and the new project lands where S01 stands
  • S02 — starting through a link never reads or writes outside the checkout and the current folder
  • S03 — the README says exactly how to make the command global
• Preconditions:
  • The checkout of RepoFoundry exists and holds config.env and .env as described in the README, or the Maintainer points to them with --config and --env.
  • A folder that is on the shell's PATH exists and the Maintainer may write to it.
• Postconditions (success guarantee):
  • A command link exists in a PATH folder and leads to the script in the checkout.
  • The Maintainer started the script by that name from a working folder, and use case [UC-001] ran with that working folder as its base: the default directory of the new project is ./<name> under it.
  • Nothing was written outside the working folder and the new project.

Main Success Scenario

1. The Maintainer makes the script reachable by name: creates a command link in a PATH folder that leads to src/create-project.sh in the checkout (the README gives the command).
2. The Maintainer opens a shell in the folder in which the new project is to be created (the working folder).
3. The Maintainer starts the script by the name of the command link.
4. The system follows the command link to the checkout, loads its own files from there, and reads config.env and .env from the checkout, or from the files named by --config and --env.
5. The system runs [UC-001] (<<include>>) with the working folder as the base of the default directory of the new project.
6. The system reports a summary that names the full path of the new project.

Extensions (Alternative / Exception Flows)

• 1a. The PATH folder is not writable, or not on PATH:
  1. The README names the other choices (a folder the Maintainer owns and adds to PATH, or an alias); the system is not involved.
• 3a. The command link is broken (the checkout was moved or removed):
  1. The shell reports that the command cannot run; the README says how to recreate the link.
• 4a. The checkout's own files cannot be found from the link target:
  1. The system stops before any change and names the folder it looked in.
• 4b. config.env or .env is not found:
  1. The system stops before any change, names the path it looked in and says that --config and --env can point elsewhere.

Special Requirements / Business Rules

Step	Rule
1	The command link is made by the Maintainer with the shell, not by the script; the script never edits PATH, a shell profile or a system folder
4	The system finds its own files by following the command link, however many links lie on the way, on every supported platform
4	config.env and .env are read from the checkout, never from the working folder, unless --config and --env name them
5	The base of the default directory is the working folder, never the checkout
3 to 6	Behaviour, prompts and summary are the same as when the script is started by its path from the checkout

Open Issues

• The README example is tested on Linux, macOS and Git Bash on Windows (MIL-007 criterion 6).

---