uspecs 0.1.0-a0, 2026-02-24T13:32:43Z

AGENTS.md

@@ -1,6 +1,6 @@
 # Agents instructions
 
-<!-- uspecs:triggering_instructions:begin -->
+<!-- uspecs:begin -->
 
 ## Execution instructions
 
@@ -12,7 +12,8 @@ When a request mentions one of the words below, you must read the corresponding
 - usync: `uspecs/u/actn-usync.md`
 - udecs: `uspecs/u/actn-udecs.md`
 - uhow: `uspecs/u/actn-uhow.md`
+- upr: `uspecs/u/actn-upr.md`
 
 Use files from `./uspecs/u` as an initial reference when user mentions uspecs
 
-<!-- uspecs:triggering_instructions:end -->
+<!-- uspecs:end -->

uspecs/u/actn-uarchive.md

@@ -15,11 +15,19 @@ Parameters:
 - Input
   - Active Change Folder path
 - Output
-  - Folder moved to `$changes_folder/archive`
+  - Folder moved to `{changes_folder}/archive`
+  - If on PR branch and Engineer confirms: git commit and push with message, branch and refs removed
 
 Flow:
 
-- Identify Active Change Folder to archive, if unclear, ask user to specify folder name
-- Execute `bash uspecs/u/scripts/uspecs.sh change archive <change-folder-name>`
-  - Example: `bash uspecs/u/scripts/uspecs.sh change archive 2602211523-check-cmd-availability`
-- Analyze output, show to user and stop
+- 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`
+    - 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

uspecs/u/actn-uchange.md

@@ -15,8 +15,8 @@ Parameters:
 - Input
   - Change description
   - --branch option (optional): create git branch for the change
-  - Issue reference (optional): URL to a GitLab/GitHub/Jira issue that prompted the change
-    - Referenced further as `$issue_url`
+  - 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)
@@ -26,12 +26,12 @@ Flow:
 
 - Determine `change_name` from the change description: kebab-case, 15-30 chars, descriptive
 - Run script to create Change Folder:
-  - Base command: `bash uspecs/u/scripts/uspecs.sh change new $change_name`
-  - If issue reference provided add `--issue-url $issue_url` parameters
+  - Base command: `bash uspecs/u/scripts/uspecs.sh change new {change_name}`
+  - If issue reference provided add `--issue-url "{issue_url}"` parameters (quoted to handle shell-special characters such as `&`)
   - 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
-- Write Change File body (`$templates_folder/tmpl-change.md`) appended to Change File created by the script
+- Write Change File body (`{templates_folder}/tmpl-change.md`) appended to Change File created by the script
 - If issue reference provided:
   - Try to fetch issue content
   - If fetch succeeds:

uspecs/u/actn-udecs.md

@@ -20,7 +20,7 @@ Parameters:
   - Optional: area focus (natural language like "focus on authentication", "clarify database design")
   - Optional: web search (--web flag or phrases like "with web search", "use web", "web")
 - Output
-  - Updated Decision File (see `$templates_folder/tmpl-decs.md`)
+  - Updated Decision File (see `{templates_folder}/tmpl-decs.md`)
 
 ## Scenarios
 

uspecs/u/actn-uhow.md

@@ -17,7 +17,7 @@ Parameters:
   - Change File and other files in Active Change Folder
   - Existing How File (if any)
 - Output
-  - Updated How File (see `$templates_folder/tmpl-how.md`)
+  - Updated How File (see `{templates_folder}/tmpl-how.md`)
 
 ## Scenarios
 

uspecs/u/actn-uimpl.md

@@ -32,7 +32,7 @@ Flow:
   - For "some to-do items unchecked" scenario: Implement each unchecked item and check it immediately after implementation (stop at Review Item if unchecked)
   - For edge cases: Follow the specific scenario behavior
 
-Use definitions from sections below and structures from `$templates_folder/tmpl-impl.md` when executing actions
+Use definitions from sections below and structures from `{templates_folder}/tmpl-impl.md` when executing actions
 
 ## Definitions
 
@@ -41,7 +41,7 @@ Use definitions from sections below and structures from `$templates_folder/tmpl-
 The section is needed if:
 
 - Domain Files exist and define External actors
-- Change Request description impacts Functional Design Specifications (only files inside `$specs_folder`)
+- Change Request description impacts Functional Design Specifications (only files inside `{specs_folder}`)
 
 Impact:
 

uspecs/u/actn-upr.md

@@ -0,0 +1,48 @@
+# Action: Create pull request
+
+## Overview
+
+Create a pull request from the current change branch by squash-merging it into a dedicated PR branch and submitting via GitHub CLI.
+
+## Instructions
+
+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
+- Read `change.md` frontmatter to determine `issue_url` and `issue_id`
+
+Parameters:
+
+- Input
+  - Active Change Folder (change.md for issue_url)
+  - change_branch: current git branch
+- Output
+  - PR created on GitHub
+  - pr_branch: `{change_branch}--pr` with squashed commits
+  - change_branch deleted
+
+Flow:
+
+- Validate preconditions:
+  - Run `bash uspecs/u/scripts/uspecs.sh pr mergedef --validate`
+  - If script exits with error: report the error and stop
+  - Parse `change_branch` and `default_branch` 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)
+- Present Engineer with the following options:
+    1. Create PR (squash-merge `change_branch` into `{change_branch}--pr`, delete `change_branch`, create PR on GitHub)
+    2. Cancel
+  - On option 2: stop
+- Merge default branch into change_branch:
+  - Run `bash uspecs/u/scripts/uspecs.sh pr mergedef`
+  - If script exits with error: report the error and stop
+  - If merge fails (conflicts): report error and ask Engineer to resolve conflicts and re-run
+- Get specs diff to derive PR title and body:
+  - Run `bash uspecs/u/scripts/uspecs.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}"`
+  - 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
+- Report `pr_url` to Engineer; inform that Engineer is now on `pr_branch` to address review comments

uspecs/u/conf.md

@@ -6,7 +6,7 @@ All paths are relative to the project root:
 
 - specs_folder: uspecs/specs
 - changes_folder: uspecs/changes
-- changes_archive: `$changes_folder/archive`
+- changes_archive: `{changes_folder}/archive`
 - templates_folder: uspecs/u/templates
 
 ## Artifacts
@@ -18,13 +18,17 @@ All paths are relative to the project root:
     - Focus on core action or feature, avoid redundant words
     - Use abbreviations when appropriate to reduce length
     - Examples: `remove-uspecs-prefix`, `fetch-issue-to-change`, `alpha-code-bp3-endpoints`
-  - Can be either Active (in `$changes_folder`) or Archived (in `$changes_archive`)
+  - 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 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
 - Change Folder System Artifacts
   - Change File: `change.md`
   - Issue File: `issue.md`
@@ -34,13 +38,13 @@ All paths are relative to the project root:
     - Clarification and brainstorming about Change Request functional and technical design
   - How File: `how.md`
     - Implementation approach idea for a Change Request
-- Domain Folder: `$specs_folder/{domain}/`
-- Context Folder: `$specs_folder/{domain}/{context-id}/`
+- Domain Folder: `{specs_folder}/{domain}/`
+- Context Folder: `{specs_folder}/{domain}/{context-id}/`
   - Contains
     - 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}--domain.md`
   - Feature Files
     - Scenarios File: `{context-folder}/{feature}.feature`
     - Requirements File: `{context-folder}/{feature}--reqs.md`
@@ -49,12 +53,12 @@ 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}/{domain}--tech.md`
     - Defines tech stack, architecture patterns etc., UI/UX guidelines etc.
   - Domain Architecture
-    - `$specs_folder/{domain}/{domain}--arch.md`
+    - `{specs_folder}/{domain}/{domain}--arch.md`
   - Domain Subsystem Architecture
-     or `$specs_folder/{domain}/{subsystem}--arch.md`
+     or `{specs_folder}/{domain}/{subsystem}--arch.md`
   - Context Architecture
     - `{context-folder}/{context}--arch.md`
   - Context Subsystem Architecture