feat(agent-context): add PowerShell script to update agent context files (edb1c2ad) · Commits · Jan Reimes / 3gpp-crawler

.gitignore

+9 −0

Original line number	Diff line number	Diff line
		@@ -221,3 +221,12 @@ __marimo__/
		/cache
		.opencode/opencode.json
		.grepai/
		.opencode/command/speckit.analyze.md
		.opencode/command/speckit.checklist.md
		.opencode/command/speckit.clarify.md
		.opencode/command/speckit.constitution.md
		.opencode/command/speckit.implement.md
		.opencode/command/speckit.plan.md
		.opencode/command/speckit.specify.md
		.opencode/command/speckit.tasks.md
		.opencode/command/speckit.taskstoissues.md

.specify/memory/constitution.md

0 → 100644

+50 −0

Original line number	Diff line number	Diff line
		# [PROJECT_NAME] Constitution
		<!-- Example: Spec Constitution, TaskFlow Constitution, etc. -->

		## Core Principles

		### [PRINCIPLE_1_NAME]
		<!-- Example: I. Library-First -->
		[PRINCIPLE_1_DESCRIPTION]
		<!-- Example: Every feature starts as a standalone library; Libraries must be self-contained, independently testable, documented; Clear purpose required - no organizational-only libraries -->

		### [PRINCIPLE_2_NAME]
		<!-- Example: II. CLI Interface -->
		[PRINCIPLE_2_DESCRIPTION]
		<!-- Example: Every library exposes functionality via CLI; Text in/out protocol: stdin/args → stdout, errors → stderr; Support JSON + human-readable formats -->

		### [PRINCIPLE_3_NAME]
		<!-- Example: III. Test-First (NON-NEGOTIABLE) -->
		[PRINCIPLE_3_DESCRIPTION]
		<!-- Example: TDD mandatory: Tests written → User approved → Tests fail → Then implement; Red-Green-Refactor cycle strictly enforced -->

		### [PRINCIPLE_4_NAME]
		<!-- Example: IV. Integration Testing -->
		[PRINCIPLE_4_DESCRIPTION]
		<!-- Example: Focus areas requiring integration tests: New library contract tests, Contract changes, Inter-service communication, Shared schemas -->

		### [PRINCIPLE_5_NAME]
		<!-- Example: V. Observability, VI. Versioning & Breaking Changes, VII. Simplicity -->
		[PRINCIPLE_5_DESCRIPTION]
		<!-- Example: Text I/O ensures debuggability; Structured logging required; Or: MAJOR.MINOR.BUILD format; Or: Start simple, YAGNI principles -->

		## [SECTION_2_NAME]
		<!-- Example: Additional Constraints, Security Requirements, Performance Standards, etc. -->

		[SECTION_2_CONTENT]
		<!-- Example: Technology stack requirements, compliance standards, deployment policies, etc. -->

		## [SECTION_3_NAME]
		<!-- Example: Development Workflow, Review Process, Quality Gates, etc. -->

		[SECTION_3_CONTENT]
		<!-- Example: Code review requirements, testing gates, deployment approval process, etc. -->

		## Governance
		<!-- Example: Constitution supersedes all other practices; Amendments require documentation, approval, migration plan -->

		[GOVERNANCE_RULES]
		<!-- Example: All PRs/reviews must verify compliance; Complexity must be justified; Use [GUIDANCE_FILE] for runtime development guidance -->

		Version: [CONSTITUTION_VERSION] \| Ratified: [RATIFICATION_DATE] \| Last Amended: [LAST_AMENDED_DATE]
		<!-- Example: Version: 2.1.1 \| Ratified: 2025-06-13 \| Last Amended: 2025-07-16 -->

.specify/scripts/powershell/check-prerequisites.ps1

0 → 100644

+148 −0

Original line number	Diff line number	Diff line
		#!/usr/bin/env pwsh

		# Consolidated prerequisite checking script (PowerShell)
		#
		# This script provides unified prerequisite checking for Spec-Driven Development workflow.
		# It replaces the functionality previously spread across multiple scripts.
		#
		# Usage: ./check-prerequisites.ps1 [OPTIONS]
		#
		# OPTIONS:
		# -Json Output in JSON format
		# -RequireTasks Require tasks.md to exist (for implementation phase)
		# -IncludeTasks Include tasks.md in AVAILABLE_DOCS list
		# -PathsOnly Only output path variables (no validation)
		# -Help, -h Show help message

		[CmdletBinding()]
		param(
		[switch]$Json,
		[switch]$RequireTasks,
		[switch]$IncludeTasks,
		[switch]$PathsOnly,
		[switch]$Help
		)

		$ErrorActionPreference = 'Stop'

		# Show help if requested
		if ($Help) {
		Write-Output @"
		Usage: check-prerequisites.ps1 [OPTIONS]

		Consolidated prerequisite checking for Spec-Driven Development workflow.

		OPTIONS:
		-Json Output in JSON format
		-RequireTasks Require tasks.md to exist (for implementation phase)
		-IncludeTasks Include tasks.md in AVAILABLE_DOCS list
		-PathsOnly Only output path variables (no prerequisite validation)
		-Help, -h Show this help message

		EXAMPLES:
		# Check task prerequisites (plan.md required)
		.\check-prerequisites.ps1 -Json

		# Check implementation prerequisites (plan.md + tasks.md required)
		.\check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks

		# Get feature paths only (no validation)
		.\check-prerequisites.ps1 -PathsOnly

		"@
		exit 0
		}

		# Source common functions
		. "$PSScriptRoot/common.ps1"

		# Get feature paths and validate branch
		$paths = Get-FeaturePathsEnv

		if (-not (Test-FeatureBranch -Branch $paths.CURRENT_BRANCH -HasGit:$paths.HAS_GIT)) {
		exit 1
		}

		# If paths-only mode, output paths and exit (support combined -Json -PathsOnly)
		if ($PathsOnly) {
		if ($Json) {
		[PSCustomObject]@{
		REPO_ROOT = $paths.REPO_ROOT
		BRANCH = $paths.CURRENT_BRANCH
		FEATURE_DIR = $paths.FEATURE_DIR
		FEATURE_SPEC = $paths.FEATURE_SPEC
		IMPL_PLAN = $paths.IMPL_PLAN
		TASKS = $paths.TASKS
		} \| ConvertTo-Json -Compress
		} else {
		Write-Output "REPO_ROOT: $($paths.REPO_ROOT)"
		Write-Output "BRANCH: $($paths.CURRENT_BRANCH)"
		Write-Output "FEATURE_DIR: $($paths.FEATURE_DIR)"
		Write-Output "FEATURE_SPEC: $($paths.FEATURE_SPEC)"
		Write-Output "IMPL_PLAN: $($paths.IMPL_PLAN)"
		Write-Output "TASKS: $($paths.TASKS)"
		}
		exit 0
		}

		# Validate required directories and files
		if (-not (Test-Path $paths.FEATURE_DIR -PathType Container)) {
		Write-Output "ERROR: Feature directory not found: $($paths.FEATURE_DIR)"
		Write-Output "Run /speckit.specify first to create the feature structure."
		exit 1
		}

		if (-not (Test-Path $paths.IMPL_PLAN -PathType Leaf)) {
		Write-Output "ERROR: plan.md not found in $($paths.FEATURE_DIR)"
		Write-Output "Run /speckit.plan first to create the implementation plan."
		exit 1
		}

		# Check for tasks.md if required
		if ($RequireTasks -and -not (Test-Path $paths.TASKS -PathType Leaf)) {
		Write-Output "ERROR: tasks.md not found in $($paths.FEATURE_DIR)"
		Write-Output "Run /speckit.tasks first to create the task list."
		exit 1
		}

		# Build list of available documents
		$docs = @()

		# Always check these optional docs
		if (Test-Path $paths.RESEARCH) { $docs += 'research.md' }
		if (Test-Path $paths.DATA_MODEL) { $docs += 'data-model.md' }

		# Check contracts directory (only if it exists and has files)
		if ((Test-Path $paths.CONTRACTS_DIR) -and (Get-ChildItem -Path $paths.CONTRACTS_DIR -ErrorAction SilentlyContinue \| Select-Object -First 1)) {
		$docs += 'contracts/'
		}

		if (Test-Path $paths.QUICKSTART) { $docs += 'quickstart.md' }

		# Include tasks.md if requested and it exists
		if ($IncludeTasks -and (Test-Path $paths.TASKS)) {
		$docs += 'tasks.md'
		}

		# Output results
		if ($Json) {
		# JSON output
		[PSCustomObject]@{
		FEATURE_DIR = $paths.FEATURE_DIR
		AVAILABLE_DOCS = $docs
		} \| ConvertTo-Json -Compress
		} else {
		# Text output
		Write-Output "FEATURE_DIR:$($paths.FEATURE_DIR)"
		Write-Output "AVAILABLE_DOCS:"

		# Show status of each potential document
		Test-FileExists -Path $paths.RESEARCH -Description 'research.md' \| Out-Null
		Test-FileExists -Path $paths.DATA_MODEL -Description 'data-model.md' \| Out-Null
		Test-DirHasFiles -Path $paths.CONTRACTS_DIR -Description 'contracts/' \| Out-Null
		Test-FileExists -Path $paths.QUICKSTART -Description 'quickstart.md' \| Out-Null

		if ($IncludeTasks) {
		Test-FileExists -Path $paths.TASKS -Description 'tasks.md' \| Out-Null
		}
		}

.specify/scripts/powershell/common.ps1

0 → 100644

+137 −0

Original line number	Diff line number	Diff line
		#!/usr/bin/env pwsh
		# Common PowerShell functions analogous to common.sh

		function Get-RepoRoot {
		try {
		$result = git rev-parse --show-toplevel 2>$null
		if ($LASTEXITCODE -eq 0) {
		return $result
		}
		} catch {
		# Git command failed
		}

		# Fall back to script location for non-git repos
		return (Resolve-Path (Join-Path $PSScriptRoot "../../..")).Path
		}

		function Get-CurrentBranch {
		# First check if SPECIFY_FEATURE environment variable is set
		if ($env:SPECIFY_FEATURE) {
		return $env:SPECIFY_FEATURE
		}

		# Then check git if available
		try {
		$result = git rev-parse --abbrev-ref HEAD 2>$null
		if ($LASTEXITCODE -eq 0) {
		return $result
		}
		} catch {
		# Git command failed
		}

		# For non-git repos, try to find the latest feature directory
		$repoRoot = Get-RepoRoot
		$specsDir = Join-Path $repoRoot "specs"

		if (Test-Path $specsDir) {
		$latestFeature = ""
		$highest = 0

		Get-ChildItem -Path $specsDir -Directory \| ForEach-Object {
		if ($_.Name -match '^(\d{3})-') {
		$num = [int]$matches[1]
		if ($num -gt $highest) {
		$highest = $num
		$latestFeature = $_.Name
		}
		}
		}

		if ($latestFeature) {
		return $latestFeature
		}
		}

		# Final fallback
		return "main"
		}

		function Test-HasGit {
		try {
		git rev-parse --show-toplevel 2>$null \| Out-Null
		return ($LASTEXITCODE -eq 0)
		} catch {
		return $false
		}
		}

		function Test-FeatureBranch {
		param(
		[string]$Branch,
		[bool]$HasGit = $true
		)

		# For non-git repos, we can't enforce branch naming but still provide output
		if (-not $HasGit) {
		Write-Warning "[specify] Warning: Git repository not detected; skipped branch validation"
		return $true
		}

		if ($Branch -notmatch '^[0-9]{3}-') {
		Write-Output "ERROR: Not on a feature branch. Current branch: $Branch"
		Write-Output "Feature branches should be named like: 001-feature-name"
		return $false
		}
		return $true
		}

		function Get-FeatureDir {
		param([string]$RepoRoot, [string]$Branch)
		Join-Path $RepoRoot "specs/$Branch"
		}

		function Get-FeaturePathsEnv {
		$repoRoot = Get-RepoRoot
		$currentBranch = Get-CurrentBranch
		$hasGit = Test-HasGit
		$featureDir = Get-FeatureDir -RepoRoot $repoRoot -Branch $currentBranch

		[PSCustomObject]@{
		REPO_ROOT = $repoRoot
		CURRENT_BRANCH = $currentBranch
		HAS_GIT = $hasGit
		FEATURE_DIR = $featureDir
		FEATURE_SPEC = Join-Path $featureDir 'spec.md'
		IMPL_PLAN = Join-Path $featureDir 'plan.md'
		TASKS = Join-Path $featureDir 'tasks.md'
		RESEARCH = Join-Path $featureDir 'research.md'
		DATA_MODEL = Join-Path $featureDir 'data-model.md'
		QUICKSTART = Join-Path $featureDir 'quickstart.md'
		CONTRACTS_DIR = Join-Path $featureDir 'contracts'
		}
		}

		function Test-FileExists {
		param([string]$Path, [string]$Description)
		if (Test-Path -Path $Path -PathType Leaf) {
		Write-Output " ✓ $Description"
		return $true
		} else {
		Write-Output " ✗ $Description"
		return $false
		}
		}

		function Test-DirHasFiles {
		param([string]$Path, [string]$Description)
		if ((Test-Path -Path $Path -PathType Container) -and (Get-ChildItem -Path $Path -ErrorAction SilentlyContinue \| Where-Object { -not $_.PSIsContainer } \| Select-Object -First 1)) {
		Write-Output " ✓ $Description"
		return $true
		} else {
		Write-Output " ✗ $Description"
		return $false
		}
		}

.specify/scripts/powershell/create-new-feature.ps1

0 → 100644

+283 −0

Original line number	Diff line number	Diff line
		#!/usr/bin/env pwsh
		# Create a new feature
		[CmdletBinding()]
		param(
		[switch]$Json,
		[string]$ShortName,
		[int]$Number = 0,
		[switch]$Help,
		[Parameter(ValueFromRemainingArguments = $true)]
		[string[]]$FeatureDescription
		)
		$ErrorActionPreference = 'Stop'

		# Show help if requested
		if ($Help) {
		Write-Host "Usage: ./create-new-feature.ps1 [-Json] [-ShortName <name>] [-Number N] <feature description>"
		Write-Host ""
		Write-Host "Options:"
		Write-Host " -Json Output in JSON format"
		Write-Host " -ShortName <name> Provide a custom short name (2-4 words) for the branch"
		Write-Host " -Number N Specify branch number manually (overrides auto-detection)"
		Write-Host " -Help Show this help message"
		Write-Host ""
		Write-Host "Examples:"
		Write-Host " ./create-new-feature.ps1 'Add user authentication system' -ShortName 'user-auth'"
		Write-Host " ./create-new-feature.ps1 'Implement OAuth2 integration for API'"
		exit 0
		}

		# Check if feature description provided
		if (-not $FeatureDescription -or $FeatureDescription.Count -eq 0) {
		Write-Error "Usage: ./create-new-feature.ps1 [-Json] [-ShortName <name>] <feature description>"
		exit 1
		}

		$featureDesc = ($FeatureDescription -join ' ').Trim()

		# Resolve repository root. Prefer git information when available, but fall back
		# to searching for repository markers so the workflow still functions in repositories that
		# were initialized with --no-git.
		function Find-RepositoryRoot {
		param(
		[string]$StartDir,
		[string[]]$Markers = @('.git', '.specify')
		)
		$current = Resolve-Path $StartDir
		while ($true) {
		foreach ($marker in $Markers) {
		if (Test-Path (Join-Path $current $marker)) {
		return $current
		}
		}
		$parent = Split-Path $current -Parent
		if ($parent -eq $current) {
		# Reached filesystem root without finding markers
		return $null
		}
		$current = $parent
		}
		}

		function Get-HighestNumberFromSpecs {
		param([string]$SpecsDir)

		$highest = 0
		if (Test-Path $SpecsDir) {
		Get-ChildItem -Path $SpecsDir -Directory \| ForEach-Object {
		if ($_.Name -match '^(\d+)') {
		$num = [int]$matches[1]
		if ($num -gt $highest) { $highest = $num }
		}
		}
		}
		return $highest
		}

		function Get-HighestNumberFromBranches {
		param()

		$highest = 0
		try {
		$branches = git branch -a 2>$null
		if ($LASTEXITCODE -eq 0) {
		foreach ($branch in $branches) {
		# Clean branch name: remove leading markers and remote prefixes
		$cleanBranch = $branch.Trim() -replace '^\*?\s+', '' -replace '^remotes/[^/]+/', ''

		# Extract feature number if branch matches pattern ###-*
		if ($cleanBranch -match '^(\d+)-') {
		$num = [int]$matches[1]
		if ($num -gt $highest) { $highest = $num }
		}
		}
		}
		} catch {
		# If git command fails, return 0
		Write-Verbose "Could not check Git branches: $_"
		}
		return $highest
		}

		function Get-NextBranchNumber {
		param(
		[string]$SpecsDir
		)

		# Fetch all remotes to get latest branch info (suppress errors if no remotes)
		try {
		git fetch --all --prune 2>$null \| Out-Null
		} catch {
		# Ignore fetch errors
		}

		# Get highest number from ALL branches (not just matching short name)
		$highestBranch = Get-HighestNumberFromBranches

		# Get highest number from ALL specs (not just matching short name)
		$highestSpec = Get-HighestNumberFromSpecs -SpecsDir $SpecsDir

		# Take the maximum of both
		$maxNum = [Math]::Max($highestBranch, $highestSpec)

		# Return next number
		return $maxNum + 1
		}

		function ConvertTo-CleanBranchName {
		param([string]$Name)

		return $Name.ToLower() -replace '[^a-z0-9]', '-' -replace '-{2,}', '-' -replace '^-', '' -replace '-$', ''
		}
		$fallbackRoot = (Find-RepositoryRoot -StartDir $PSScriptRoot)
		if (-not $fallbackRoot) {
		Write-Error "Error: Could not determine repository root. Please run this script from within the repository."
		exit 1
		}

		try {
		$repoRoot = git rev-parse --show-toplevel 2>$null
		if ($LASTEXITCODE -eq 0) {
		$hasGit = $true
		} else {
		throw "Git not available"
		}
		} catch {
		$repoRoot = $fallbackRoot
		$hasGit = $false
		}

		Set-Location $repoRoot

		$specsDir = Join-Path $repoRoot 'specs'
		New-Item -ItemType Directory -Path $specsDir -Force \| Out-Null

		# Function to generate branch name with stop word filtering and length filtering
		function Get-BranchName {
		param([string]$Description)

		# Common stop words to filter out
		$stopWords = @(
		'i', 'a', 'an', 'the', 'to', 'for', 'of', 'in', 'on', 'at', 'by', 'with', 'from',
		'is', 'are', 'was', 'were', 'be', 'been', 'being', 'have', 'has', 'had',
		'do', 'does', 'did', 'will', 'would', 'should', 'could', 'can', 'may', 'might', 'must', 'shall',
		'this', 'that', 'these', 'those', 'my', 'your', 'our', 'their',
		'want', 'need', 'add', 'get', 'set'
		)

		# Convert to lowercase and extract words (alphanumeric only)
		$cleanName = $Description.ToLower() -replace '[^a-z0-9\s]', ' '
		$words = $cleanName -split '\s+' \| Where-Object { $_ }

		# Filter words: remove stop words and words shorter than 3 chars (unless they're uppercase acronyms in original)
		$meaningfulWords = @()
		foreach ($word in $words) {
		# Skip stop words
		if ($stopWords -contains $word) { continue }

		# Keep words that are length >= 3 OR appear as uppercase in original (likely acronyms)
		if ($word.Length -ge 3) {
		$meaningfulWords += $word
		} elseif ($Description -match "\b$($word.ToUpper())\b") {
		# Keep short words if they appear as uppercase in original (likely acronyms)
		$meaningfulWords += $word
		}
		}

		# If we have meaningful words, use first 3-4 of them
		if ($meaningfulWords.Count -gt 0) {
		$maxWords = if ($meaningfulWords.Count -eq 4) { 4 } else { 3 }
		$result = ($meaningfulWords \| Select-Object -First $maxWords) -join '-'
		return $result
		} else {
		# Fallback to original logic if no meaningful words found
		$result = ConvertTo-CleanBranchName -Name $Description
		$fallbackWords = ($result -split '-') \| Where-Object { $_ } \| Select-Object -First 3
		return [string]::Join('-', $fallbackWords)
		}
		}

		# Generate branch name
		if ($ShortName) {
		# Use provided short name, just clean it up
		$branchSuffix = ConvertTo-CleanBranchName -Name $ShortName
		} else {
		# Generate from description with smart filtering
		$branchSuffix = Get-BranchName -Description $featureDesc
		}

		# Determine branch number
		if ($Number -eq 0) {
		if ($hasGit) {
		# Check existing branches on remotes
		$Number = Get-NextBranchNumber -SpecsDir $specsDir
		} else {
		# Fall back to local directory check
		$Number = (Get-HighestNumberFromSpecs -SpecsDir $specsDir) + 1
		}
		}

		$featureNum = ('{0:000}' -f $Number)
		$branchName = "$featureNum-$branchSuffix"

		# GitHub enforces a 244-byte limit on branch names
		# Validate and truncate if necessary
		$maxBranchLength = 244
		if ($branchName.Length -gt $maxBranchLength) {
		# Calculate how much we need to trim from suffix
		# Account for: feature number (3) + hyphen (1) = 4 chars
		$maxSuffixLength = $maxBranchLength - 4

		# Truncate suffix
		$truncatedSuffix = $branchSuffix.Substring(0, [Math]::Min($branchSuffix.Length, $maxSuffixLength))
		# Remove trailing hyphen if truncation created one
		$truncatedSuffix = $truncatedSuffix -replace '-$', ''

		$originalBranchName = $branchName
		$branchName = "$featureNum-$truncatedSuffix"

		Write-Warning "[specify] Branch name exceeded GitHub's 244-byte limit"
		Write-Warning "[specify] Original: $originalBranchName ($($originalBranchName.Length) bytes)"
		Write-Warning "[specify] Truncated to: $branchName ($($branchName.Length) bytes)"
		}

		if ($hasGit) {
		try {
		git checkout -b $branchName \| Out-Null
		} catch {
		Write-Warning "Failed to create git branch: $branchName"
		}
		} else {
		Write-Warning "[specify] Warning: Git repository not detected; skipped branch creation for $branchName"
		}

		$featureDir = Join-Path $specsDir $branchName
		New-Item -ItemType Directory -Path $featureDir -Force \| Out-Null

		$template = Join-Path $repoRoot '.specify/templates/spec-template.md'
		$specFile = Join-Path $featureDir 'spec.md'
		if (Test-Path $template) {
		Copy-Item $template $specFile -Force
		} else {
		New-Item -ItemType File -Path $specFile \| Out-Null
		}

		# Set the SPECIFY_FEATURE environment variable for the current session
		$env:SPECIFY_FEATURE = $branchName

		if ($Json) {
		$obj = [PSCustomObject]@{
		BRANCH_NAME = $branchName
		SPEC_FILE = $specFile
		FEATURE_NUM = $featureNum
		HAS_GIT = $hasGit
		}
		$obj \| ConvertTo-Json -Compress
		} else {
		Write-Output "BRANCH_NAME: $branchName"
		Write-Output "SPEC_FILE: $specFile"
		Write-Output "FEATURE_NUM: $featureNum"
		Write-Output "HAS_GIT: $hasGit"
		Write-Output "SPECIFY_FEATURE environment variable set to: $branchName"
		}