uspecs 0.1.0-a0, 2026-04-01T16:21:32Z

AGENTS.md

@@ -4,16 +4,13 @@
 
 ## Execution instructions
 
-When a request mentions one of the words below, you must read the corresponding file and follow the rules described there:
+When a request starts with one of the following keywords, you must execute `bash uspecs/u/scripts/softeng.sh action {keyword}` and follow the instructions provided in the output: upr, umergepr.
 
-- uchange: `uspecs/u/actn-uchange.md`
-- uarchive: `uspecs/u/actn-uarchive.md`
-- uimpl: `uspecs/u/actn-uimpl.md`
-- usync: `uspecs/u/actn-usync.md`
-- udecs: `uspecs/u/actn-udecs.md`
-- uhow: `uspecs/u/actn-uhow.md`
-- upr: `uspecs/u/actn-upr.md`
+When a request starts with one of the keywords below, you must read the corresponding file and follow the rules described there:
 
-Use files from `./uspecs/u` as an initial reference when user mentions uspecs
+- uchange: create a change request following rules from `uspecs/u/actn-uchange.md`
+- uarchive, uimpl, usync, udecs, uhow: perform action described in `uspecs/u/actn-{keyword}.md`
+
+Use files from `./uspecs/u` as an initial reference when user mentions uspecs.
 
 <!-- uspecs:end -->

uspecs/u/actn-uarchive.md

@@ -13,21 +13,26 @@ Rules:
 Parameters:
 
 - Input
-  - Active Change Folder path
+  - Active Change Folder path (not required when `--all` is used)
+  - `--all` option (optional): archive all change folders modified vs `pr_remote/default_branch`; no Active Change Folder path needed
 - Output
-  - Folder moved to `{changes_folder}/archive`
+  - Folder(s) moved to `{changes_folder}/archive`
   - If on PR branch and Engineer confirms: git commit and push with message, branch and refs removed, deleted branch hash and restore instructions reported
 
 Flow:
 
-- Identify Active Change Folder to archive, if unclear, ask Engineer to specify folder name
-- Run `bash uspecs/u/scripts/uspecs.sh status ispr`
-  - If output is `yes`: present Engineer with the following options:
-      1. Archive + git cleanup (commit, push, delete local branch and remote tracking ref)
-      2. Archive only (no git operations)
-      3. Cancel
-    - On option 1: `bash uspecs/u/scripts/uspecs.sh change archive <change-folder-name> -d`; script output includes deleted branch hash and restore instructions - relay to Engineer
-    - On option 2: `bash uspecs/u/scripts/uspecs.sh change archive <change-folder-name>`
-    - On option 3: abort, no action taken
-  - Otherwise: `bash uspecs/u/scripts/uspecs.sh change archive <change-folder-name>`
-- Analyze output, show to Engineer and stop
+- If `--all` option is provided:
+  - Run `bash uspecs/u/scripts/softeng.sh change archiveall`
+  - Analyze output, show to Engineer and stop
+- Otherwise:
+  - Identify Active Change Folder to archive, if unclear, ask Engineer to specify folder name
+  - Run `bash uspecs/u/scripts/softeng.sh status ispr`
+    - If output is `yes`: present Engineer with the following options:
+        1. Archive + git cleanup (commit, push, delete local branch and remote tracking ref)
+        2. Archive only (no git operations)
+        3. Cancel
+      - On option 1: `bash uspecs/u/scripts/softeng.sh change archive <change-folder-name> -d`; script output includes deleted branch hash and restore instructions - relay to Engineer
+      - On option 2: `bash uspecs/u/scripts/softeng.sh change archive <change-folder-name>`
+      - On option 3: abort, no action taken
+    - Otherwise: `bash uspecs/u/scripts/softeng.sh change archive <change-folder-name>`
+  - Analyze output, show to Engineer and stop

uspecs/u/actn-uchange.md

@@ -1,33 +1,49 @@
-# Action: Create change
+# Action: Create change request
 
 ## Overview
 
-Create a new change request folder with a structured Change File. Optionally fetch issue content from an issue URL (GitLab, GitHub, Jira) and create a git branch.
+Create a new change request folder with a structured Change File.
+
+Optionally:
+
+- Fetch issue content from an issue URL (GitLab, GitHub, Jira)
+- Create a git branch
 
 ## Instructions
 
 Rules:
 
 - Always read `uspecs/u/concepts.md` and `uspecs/u/conf.md` before proceeding and follow the definitions and rules defined there
+- Never perform any implementation, code changes, or actions outside of this flow - the only output is the Change Folder, Change File, optional Issue File, git branch
+- If change description is not provided, ask the user for it before proceeding. Do not treat the response as a new command - use it as the change description and continue this flow
+- Never pass any optional parameter (`--no-branch`, `--branch`, `--issue-url`) to the script or alter default behavior unless it is explicitly requested
 
 Parameters:
 
 - Input
   - Change description
-  - --branch option (optional): create git branch for the change
+  - --no-branch option (optional): skip git branch creation
+  - --branch option (optional): force git branch creation even when not on the default branch
   - Issue reference (optional): URL to a GitLab/GitHub/Jira/etc. issue that prompted the change
     - Referenced further as `{issue_url}`
 - Output
   - Active Change Folder with Change File
   - Issue File (if issue reference provided)
-  - Git branch (if --branch option provided and git repository exists)
+  - Git branch (created by default when on the default branch; skipped when on a non-default branch unless --branch; skipped when --no-branch; git repository must exist)
 
 Flow:
 
-- Determine `change_name` from the change description: kebab-case, 15-30 chars, descriptive
+- Pre-flight checklist (verify before proceeding):
+  - [ ] I have read `uspecs/u/concepts.md` and `uspecs/u/conf.md`
+  - [ ] User has NOT explicitly requested `--no-branch` -> I will NOT pass this flag
+  - [ ] User has NOT explicitly requested `--branch` -> I will NOT pass this flag  
+  - [ ] User has NOT provided an issue URL -> I will NOT pass `--issue-url`
+  - [ ] If any of the above are explicitly requested, I will pass ONLY those flags
+- Determine `change_name` from the change description: kebab-case, max 40 chars (ideal 15-30), descriptive
 - Run script to create Change Folder:
-  - Base command: `bash uspecs/u/scripts/uspecs.sh change new {change_name}`
+  - Base command: `bash uspecs/u/scripts/softeng.sh change new {change_name}`
   - If issue reference provided add `--issue-url "{issue_url}"` parameters (quoted to handle shell-special characters such as `&`)
+  - If --no-branch option provided add `--no-branch` parameter
   - If --branch option provided add `--branch` parameter
   - Fail fast if script exits with error
   - Parse Change Folder path from script output, path is relative to project root
@@ -38,4 +54,4 @@ Flow:
     - Convert it to rich markdown format suitable for Issue File
     - Save fetched content to Issue File (issue.md) inside the Change Folder
     - Add reference to Issue File in Why section: `See [issue.md](issue.md) for details.`
-- Show user what was created and stop, do not proceed to implementation or other steps
+- Show user what was created

uspecs/u/actn-uimpl.md

@@ -10,7 +10,7 @@ Rules:
 
 - Strictly follow the definitions from `uspecs/u/concepts.md` and `uspecs/u/conf.md`
   - Use file name patterns from there, not from the codebase
-- Critical: Only one scenario must be executed per command run. After executing the action, the AI Agent must stop further processing and wait for the next command.
+- Critical: Only one Gherkin scenario branch (from the `Scenarios` section below) must be selected and entered per command run. Within that branch, all steps and to-do items are processed fully. After completing the branch, the AI Agent must stop further processing and wait for the next command.
 - All relative links must be correct paths from the file being edited to the target file. Verify that relative paths resolve to the intended file before writing them.
 
 Parameters:
@@ -38,10 +38,14 @@ Use definitions from sections below and structures from `{templates_folder}/tmpl
 
 ### `Functional design` section does not exist and it is needed
 
-The section is needed if:
+The section is needed if Domain Files exist and define External actors, and the change request impacts or implies new Functional Design Specifications (files inside `{specs_folder}`):
 
-- Domain Files exist and define External actors
-- Change Request description impacts Functional Design Specifications (only files inside `{specs_folder}`)
+- updates to existing Domain Files, Scenarios Files, or Requirements Files
+- introduction of new domains, features, or requirements not yet specified
+
+The section is NOT needed if the change request affects only internal system behavior with no impact on what external actors observe or interact with.
+
+Determine the appropriate domain, context, and feature by searching existing specification files, then decide whether to update an existing file or create a new one.
 
 Impact:
 
@@ -72,10 +76,9 @@ The section is needed if Change Request description implies:
 
 ### `Technical design` section does not exist and it is needed
 
-Follow this decision hierarchy (in order):
+Determine the appropriate domain, context, and technical design files by searching existing specification files, then follow this decision hierarchy (in order):
 
 - First priority: Update existing Technical Design Specifications
-  - Search for existing architecture and technical design files that cover the affected components
   - Update when the change request affects design elements already documented in:
     - Domain Architecture
     - Domain Subsystem Architecture

uspecs/u/actn-upr.md → uspecs/u/actn-upr_deprecated.md

@@ -9,7 +9,7 @@ Create a pull request from the current change branch by squash-merging it into a
 Rules:
 
 - Strictly follow the definitions from `uspecs/u/concepts.md` and `uspecs/u/conf.md`
-- Always call `uspecs.sh` for git/PR operations — never call `_lib/pr.sh` directly
+- Always call `softeng.sh` for git/PR operations - never call `_lib/pr.sh` directly
 - Read `change.md` frontmatter to determine `issue_url` and `issue_id`
 
 Parameters:
@@ -24,8 +24,9 @@ Parameters:
 
 Flow:
 
-- Merge default branch into change_branch:
-  - Run `bash uspecs/u/scripts/uspecs.sh pr mergedef`
+- Determine Active Change Folder path (relative to project root)
+- Preflight and merge default branch into change_branch:
+  - Run `bash uspecs/u/scripts/softeng.sh pr preflight --change-folder "{active_change_folder}"`
   - If script exits with error: report the error and stop
   - Parse `change_branch`, `default_branch`, and `change_branch_head` from script output
 - Read Active Change Folder (change.md) to determine `issue_url` (may be absent) and derive `issue_id` from the URL (last path segment)
@@ -34,10 +35,10 @@ Flow:
     2. Cancel
   - On option 2: stop
 - Get specs diff to derive PR title and body:
-  - Run `bash uspecs/u/scripts/uspecs.sh diff specs`
+  - Run `bash uspecs/u/scripts/softeng.sh diff specs`
   - From the diff output identify `draft_title` and `draft_body`; construct `pr_title` and `pr_body` per `{templates_folder}/tmpl-pr.md`
 - Create PR:
-  - Pass `pr_body` via stdin to `bash uspecs/u/scripts/uspecs.sh pr create --title "{pr_title}"`
+  - Pass `pr_body` via stdin to `bash uspecs/u/scripts/softeng.sh pr create --title "{pr_title}"`
   - Note: `pr_title` is passed on the command line; ensure it contains no shell-special characters (`<`, `>`, `$`, backticks)
   - If script exits with error: report the error and stop
   - Parse `pr_url` from script output

uspecs/u/actn-usync.md

@@ -1,33 +1,45 @@
-# Action: Sync Implementation Plan with actual modifications
+# Action: Sync Active Change Folder with actual modifications
 
 ## Overview
 
-Sync the Implementation Plan with actual file modifications since the baseline commit.
+Sync all specs and Active Change Folder files with actual source modifications since the baseline commit.
+
+Sources (everything outside `uspecs/`) are the source of truth. Sync direction:
+
+sources -> technical specs -> functional specs -> Active Change Folder files
 
 ## Instructions
 
 Rules:
 
 - Always read `uspecs/u/concepts.md` and `uspecs/u/conf.md` before proceeding
-- Track only files related to the current Change Request
-- Exclude files in the Change Request folder from analysis
-- Add items and sub-items for changes not yet reflected in the Implementation Plan
-- Update or remove wrong or outdated items and sub-items
+- Exclude files inside `uspecs/` from source analysis
+- Focus on high-level changes; avoid unnecessary detail
+  - E.g. if a scenario was added, do not list each individual step
 - Do not add more than 5 new sub-items per to-do item in a single sync
 - Never remove correct items and sub-items to reduce their count
-- Avoid adding unnecessary details, focus on high-level changes
-  - E.g. if scenario was added do not mention each step added
 
 Parameters:
 
 - Input
   - Change File frontmatter (baseline commit hash)
-  - Git diff since baseline
+  - Git diff of sources since baseline
 - Output
-  - Updated Implementation Plan
+  - Updated technical spec files
+  - Updated functional spec files
+  - Updated Active Change Folder files (all of them)
 
 Flow:
 
 - Read baseline commit hash from Change File frontmatter
-- Get diff since baseline using command: `git diff <baseline>`
-- Update Implementation Plan with what was actually done, including changes in files and file contents
+- Get diff of sources since baseline: `git diff <baseline> -- . ':(exclude)uspecs/'`
+- Step 1 - Sync technical specs
+  - Identify Technical Design Specification files related to changed sources
+  - Update them to reflect what was actually built (architecture, design decisions, component interactions)
+- Step 2 - Sync functional specs
+  - Identify Functional Design Specification files related to changed sources
+  - Update them to reflect what was actually built (scenarios, requirements, domain model)
+- Step 3 - Sync Active Change Folder files
+  - Using sources, updated technical specs, and updated functional specs as input
+  - Update all files present in the Active Change Folder (change.md, impl.md, decs.md, how.md, issue.md and others - whichever exist)
+  - Implementation Plan: add, update, or remove items and sub-items to match what was actually done

uspecs/u/conf.md

@@ -20,15 +20,19 @@ All paths are relative to the project root:
     - Examples: `remove-uspecs-prefix`, `fetch-issue-to-change`, `alpha-code-bp3-endpoints`
   - Can be either Active (in `{changes_folder}`) or Archived (in `{changes_archive}`)
   - Active Change Folder files describe Active Change Request and its implementation
-  - Branch naming for Change Folder (when --branch option used):
-    - Format: `{change-name}` (without timestamp prefix)
-    - Example: For Change Folder `2602141423-branch-option-uchange`, branch name is `branch-option-uchange`
+  - Branch naming for Change Folder:
+    - Format: `{issue-id}-{change-name}` when issue URL provided, otherwise `{change-name}` (without timestamp prefix)
+    - Issue ID extraction:
+      - GitHub: numeric ID from URL (e.g., `42` from `https://github.com/owner/repo/issues/42`)
+      - GitLab: numeric ID from URL (e.g., `7` from `https://gitlab.com/group/project/-/issues/7`)
+      - Jira: project key and issue number (e.g., `PROJ-123` from `https://jira.example.com/browse/PROJ-123`)
+    - Examples:
+      - With issue URL: For Change Folder `2602141423-branch-option-uchange` and GitHub issue #42, branch name is `42-branch-option-uchange`
+      - Without issue URL: For Change Folder `2602141423-branch-option-uchange`, branch name is `branch-option-uchange`
     - Branch is created from current HEAD after Change Folder and Change File are created
     - If branch creation fails, error is reported but change creation continues
-  - PR branch naming (created by upr):
-    - Format: `{change-name}--pr`
-    - Example: For change branch `branch-option-uchange`, PR branch is `branch-option-uchange--pr`
-    - Created from pr_remote/default_branch; contains a single squashed commit
+- Working Change Folder: a Change Folder whose files have been modified since merge-base with pr_remote/default_branch
+  - Can be active or archived
 - Change Folder System Artifacts
   - Change File: `change.md`
   - Issue File: `issue.md`
@@ -44,7 +48,7 @@ All paths are relative to the project root:
     - zero or many `Scenarios File`, `Requirements File`, `Technical Design File`
     - zero or one `Architecture File`
 - Functional Design Specifications
-  - Domain File: `{specs_folder}/{domain}/{domain}--domain.md`
+  - Domain File: `{specs_folder}/{domain}/domain.md`
   - Feature Files
     - Scenarios File: `{context-folder}/{feature}.feature`
     - Requirements File: `{context-folder}/{feature}--reqs.md`
@@ -53,16 +57,16 @@ All paths are relative to the project root:
   - Files like `go.mod`, `go.work`, `package.json`, `requirements.txt`, `pubspec.yaml` etc. that define project dependencies and configuration
 - Technical Design Specifications
   - Domain Technology
-    - Per domain: `{specs_folder}/{domain}/{domain}--tech.md`
+    - Per domain: `{specs_folder}/{domain}/tech.md`
     - Defines tech stack, architecture patterns etc., UI/UX guidelines etc.
   - Domain Architecture
-    - `{specs_folder}/{domain}/{domain}--arch.md`
+    - `{specs_folder}/{domain}/arch.md`
   - Domain Subsystem Architecture
-     or `{specs_folder}/{domain}/{subsystem}--arch.md`
+     or `{specs_folder}/{domain}/arch-{subsystem}.md`
   - Context Architecture
-    - `{context-folder}/{context}--arch.md`
+    - `{context-folder}/arch.md`
   - Context Subsystem Architecture
-     or `{context-folder}/{subsystem}--arch.md`
+     or `{context-folder}/arch-{subsystem}.md`
   - Feature Technical Design
     - Per feature: `{context-folder}/{feature}--td.md`
 

uspecs/u/prompts.md

@@ -0,0 +1,66 @@
+# Prompts
+
+## upr_already_exists: PR already exists for current branch
+
+PR already exists for the current branch: ${pr_url}
+
+It has been opened in the browser.
+
+## upr_success: Next steps after PR creation
+
+PR has been created: ${pr_url}
+
+To restore branch to its pre-squash state, if needed:
+
+```text
+git reset --hard ${pre_push_head}
+git push --force
+```
+
+Next steps:
+
+- Fix any issues raised during review
+- Run `umergepr` once the PR is approved and ready to merge
+
+## upr_success_no_squash: Next steps after PR creation
+
+PR has been created: ${pr_url}
+
+Next steps:
+
+- Fix any issues raised during review
+- Run `umergepr` once the PR is approved and ready to merge
+
+## umergepr_success: PR merged successfully
+
+PR #${pr_number} has been merged successfully: ${pr_url}
+
+Local branch `${branch_name}` and its remote tracking ref have been deleted.
+
+To restore the local branch, if needed:
+
+```text
+git branch ${branch_name} ${branch_head}
+```
+
+## umergepr_no_pr: No open PR for current branch
+
+No open PR found for the current branch.
+
+## umergepr_not_open: PR is not in OPEN state
+
+PR #${pr_number} is in ${pr_state} state (not OPEN). It has been opened in your browser.
+
+Local branch `${branch_name}`, upstream, and remote tracking ref have been deleted (errors ignored).
+
+To restore the local branch:
+
+```text
+git branch ${branch_name} ${branch_head}
+```
+
+## umergepr_merge_failed: Merge attempt failed
+
+Merge of PR #${pr_number} failed. The PR has been opened in your browser.
+
+Handle the PR manually (resolve conflicts, adjust settings, etc.) and run `umergepr` again.