PR Factory: Fix #169 Feature: Add Windows setup instructions for root quickstart and setup.sh

[mohiitt]

PR Factory Output

Closes #169

Summary

Summary

Fresh ad-hoc verification completed successfully. No new edits were made.

Committed change remains:

e6521c8 Add Windows PowerShell setup helper

Files Changed

• setup.ps1
• tests/test_setup_ps1_static.py
• README.md
• CONTRIBUTING.md
• CHANGELOG.md

Why This Fix

Adds a native Windows PowerShell setup path while preserving the existing Bash helper and macOS/Linux/Git Bash/WSL docs.

Tests Run

Ad-hoc verification only, not a full suite-green claim.

Temporary verifier created:

/var/folders/yf/3mgk15tx2sj0zt3dm420wlb00000gn/T/hermes-verify-jvuyuexq.py

Command run:

python3 /var/folders/yf/3mgk15tx2sj0zt3dm420wlb00000gn/T/hermes-verify-jvuyuexq.py

Verifier checked:

• setup.ps1 required fragments and behavior guards:
  • [string]$Example
  • [switch]$Run
  • $PSScriptRoot
  • example folder validation
  • Python 3.10+ check
  • python plus py -3 fallback
  • .venv creation
  • venv-local Scripts\python.exe
  • requirements.txt install path
  • safe .env.example copy only when .env is absent
  • entry file order: agent.py, main.py, workflow.py, app.py
  • PowerShell activation hint
  • -Run execution branch
• python3 -m py_compile tests/test_setup_ps1_static.py
• python3 -m unittest discover -s tests -v
• git diff --check HEAD~1..HEAD

Result:

RESULT: passed

Cleanup:

CLEANED_UP=/var/folders/yf/3mgk15tx2sj0zt3dm420wlb00000gn/T/hermes-verify-jvuyuexq.py

Git status from verifier:

## pr-factory/169-e58abg72-coder-b...origin/main [ahead 1]

Risks

• PowerShell is not installed locally, so this remains static/ad-hoc verification plus Python regression tests, not an actual setup.ps1 runtime execution in PowerShell.

Planner Spec

Problem

Windows users cannot follow the repository’s root quickstart/setup flow without manually translating Unix/Bash commands.

Current root setup docs and helper path are Unix-centric:

• README.md:24-48 uses python3, source .venv/bin/activate, cp .env.example .env, and ./setup.sh.
• setup.sh is explicitly Bash-only and uses Bash syntax plus Unix activation/copy commands.
• README.md:193-195 uses Bash-style inline environment variable assignment for Docker Compose.
• CONTRIBUTING.md:13 only references ./setup.sh <example-folder>.

The feature should make root setup clearly usable for native Windows PowerShell users, while preserving existing macOS/Linux behavior.

Repo Context

• Repository: fetchai/innovation-lab-examples
• Issue: #169
• Main setup documentation lives in root README.md.
• Current Bash helper lives in root setup.sh.
• The repo already has a broad examples structure; setup helpers are intended to work against arbitrary example folders.
• setup.sh behavior:
  • Usage: ./setup.sh <example-folder> [--run]
  • Validates example folder exists.
  • Detects Python 3.10+ via python3 or python.
  • Creates .venv inside the selected example folder.
  • Installs requirements.txt if present.
  • Copies .env.example to .env only when .env does not already exist.
  • Detects entry files in order: agent.py, main.py, workflow.py, app.py.
  • Optionally runs the entry file with --run.
• CI changelog behavior:
  • Markdown-only changes skip changelog.
  • Adding a non-Markdown file such as setup.ps1 requires root CHANGELOG.md to be updated.

Relevant Memory

No repository memory was provided.

Repo conventions from current files and researcher context:

• Root README style uses emoji headings, horizontal rules, compact prose, and fenced bash snippets.
• Existing Windows docs elsewhere often use inline comments like:
  • # OR on Windows PowerShell:
  • .\.venv\Scripts\Activate.ps1
• Avoid changing existing setup.sh behavior unless necessary.
• If adding a Windows helper script, prefer a sibling setup.ps1 over trying to make setup.sh cross-platform.
• If adding setup.ps1, update CHANGELOG.md under [Unreleased].
• Do not suggest permanent/global PowerShell execution policy changes; if needed, document process-scoped bypass only:
  • Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
• Be careful not to imply setup.sh works in native Windows PowerShell; it is Bash-only and should be labeled macOS/Linux/Git Bash/WSL.

Acceptance Criteria

• Root README.md includes explicit Windows PowerShell setup instructions for:
  • cloning and entering the repo,
  • selecting an example,
  • creating a venv,
  • activating the venv,
  • installing requirements,
  • copying .env.example to .env,
  • running the example.
• Root README.md clearly distinguishes:
  • macOS/Linux/Git Bash/WSL Bash commands, and
  • native Windows PowerShell commands.
• The automated setup path is Windows-friendly:
  • either add setup.ps1, or document a clear manual PowerShell equivalent.
  • Preferred: add setup.ps1 matching setup.sh behavior.
• setup.sh is documented as Bash/macOS/Linux/Git Bash/WSL only, not as native PowerShell.
• If setup.ps1 is added:
  • It accepts an example folder argument.
  • It supports an optional run flag, preferably -Run.
  • It validates the example folder exists.
  • It checks for Python 3.10+.
  • It creates .venv in the example folder if missing.
  • It installs dependencies from requirements.txt if present.
  • It copies .env.example to .env only if .env is absent.
  • It prints PowerShell-appropriate activation and run instructions.
  • It does not overwrite existing .env.
  • It updates root CHANGELOG.md.
• Docker Compose README instructions include a PowerShell equivalent for setting EXAMPLE, or avoid presenting Bash-only syntax as universal.
• Optional but recommended: CONTRIBUTING.md mentions Windows users can use .\setup.ps1 <example-folder>.

Suggested Files

• README.md

  • Primary documentation target.
  • Update quickstart section around README.md:22-50.
  • Update repository structure around README.md:64 if adding setup.ps1.
  • Update Docker Compose section around README.md:191-195 to show PowerShell syntax:
    • Bash: EXAMPLE=fetch-hackathon-quickstarter docker compose up
    • PowerShell: $env:EXAMPLE="fetch-hackathon-quickstarter"; docker compose up

• setup.ps1

  • New Windows PowerShell helper if implementing the preferred solution.
  • Should mirror setup.sh behavior closely.

• setup.sh

  • Usually no behavior change needed.
  • Possible documentation/comment-only change if desired, but avoid altering functionality.

• CHANGELOG.md

  • Required if setup.ps1 is added.
  • Add an [Unreleased] entry under ### Added, e.g. Windows PowerShell setup helper and README setup instructions.

• CONTRIBUTING.md

  • Optional secondary docs update.
  • Update CONTRIBUTING.md:13 to mention PowerShell alternative.

Implementation Tasks

1. Inspect current setup docs and script behavior.

   • Read README.md, setup.sh, CONTRIBUTING.md, CHANGELOG.md, and .github/workflows/pull_request_ci.yml.
   • Confirm exact wording and CI changelog requirement before editing.

2. Update root quickstart docs.

   • Split the quickstart into either:
     • “macOS/Linux/Git Bash/WSL” and “Windows PowerShell”, or
     • a shared intro plus two clearly labeled command blocks.
   • Use python for Windows PowerShell.
   • Use .\.venv\Scripts\Activate.ps1.
   • Use Copy-Item .env.example .env.
   • Keep the existing example target fetch-hackathon-quickstarter.

3. Add or document Windows automated setup.

   • Preferred: create root setup.ps1.
   • Show usage in README:
     • .\setup.ps1 fetch-hackathon-quickstarter
     • optionally .\setup.ps1 fetch-hackathon-quickstarter -Run
   • Mention process-scoped execution policy workaround only if script execution is blocked:
     • Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

4. Implement setup.ps1 if chosen.

   • Use idiomatic PowerShell.
   • Define parameters:
     • required [string]$Example
     • optional [switch]$Run
   • Determine repo root via $PSScriptRoot.
   • Resolve target example folder.
   • Validate Python 3.10+ using python --version and/or py -3 --version.
   • Create .venv with python -m venv .venv.
   • Activate by invoking the venv Python/pip directly rather than relying on activation side effects where practical:
     • .\.venv\Scripts\python.exe -m pip install --upgrade pip
     • .\.venv\Scripts\python.exe -m pip install -r requirements.txt
   • Copy .env.example to .env only if .env is missing.
   • Detect entry file in the same order as setup.sh.
   • If -Run is provided, run the entry file with the venv Python.
   • Print final activation command using PowerShell syntax.

5. Update repository structure docs if adding setup.ps1.

   • In README.md, add setup.ps1 near setup.sh.
   • Clarify setup.sh is Bash/macOS/Linux and setup.ps1 is Windows PowerShell.

6. Update Docker Compose docs.

   • Add a PowerShell equivalent for EXAMPLE=... docker compose up.
   • Avoid expanding unrelated Docker docs.

7. Update CONTRIBUTING.md if within scope.

   • Change the setup helper sentence to include:
     • macOS/Linux/Git Bash/WSL: ./setup.sh <example-folder>
     • Windows PowerShell: .\setup.ps1 <example-folder>

8. Update CHANGELOG.md if adding setup.ps1.

   • Add a concise [Unreleased] -> Added bullet for the Windows PowerShell setup helper and root README instructions.

Test Plan

Required configured validation:

• git diff --check

If only Markdown files are changed:

• git diff --check is sufficient for the configured test command.
• Also manually review rendered Markdown structure for correct code fences and shell labels.

If setup.ps1 is added:

• Run git diff --check.
• If PowerShell is installed:
  • pwsh -NoProfile -Command '$null = [System.Management.Automation.Language.Parser]::ParseFile("setup.ps1", [ref]$null, [ref]$errors); if ($errors.Count) { $errors | Format-List; exit 1 }'
• If pwsh is not installed:
  • note in the final handoff that PowerShell syntax validation could not be run locally.
• Optional stronger validation if feasible on the environment:
  • run the script against a small existing example that has requirements.txt, but avoid requiring real API keys.
  • Ensure it does not overwrite an existing .env.

Expected CI implications:

• Markdown-only change skips changelog check.
• Adding setup.ps1 requires CHANGELOG.md.
• No Python files should be changed, so ruff/mypy should not be relevant.

Coder A Strategy: Minimal Safe Fix

Aim: Resolve the issue with the smallest low-risk documentation change.

1. Modify README.md only.

   • Split current quickstart into:
     • macOS/Linux/Git Bash/WSL commands.
     • Windows PowerShell commands.
   • Keep existing Bash commands mostly intact.
   • Add PowerShell equivalents:
     • python -m venv .venv
     • .\.venv\Scripts\Activate.ps1
     • pip install -r requirements.txt
     • Copy-Item .env.example .env
     • python agents/alice/agent.py

2. Clarify automated script limitation.

   • Change “Or use the automated setup script” to indicate:
     • ./setup.sh is for macOS/Linux/Git Bash/WSL.
     • native Windows users should use the PowerShell manual steps above.
   • Mention execution policy only if adding any PowerShell script; otherwise skip it.

3. Update Docker Compose command with a PowerShell equivalent.

   • Add a second code block or comments:
     • Bash:
       EXAMPLE=fetch-hackathon-quickstarter docker compose up
     • PowerShell:
       $env:EXAMPLE="fetch-hackathon-quickstarter"; docker compose up

4. Do not add setup.ps1.

   • This avoids changelog requirement and script runtime risk.
   • This may be acceptable because the issue says “either add a setup.ps1 helper or make existing setup instructions clearly cross-platform.”

5. Run:

   • git diff --check

Tradeoff:

• Fastest and safest.
• May be seen as incomplete if maintainers strongly expect an actual Windows-friendly setup helper.

Coder B Strategy: Test-First Comprehensive Fix

Aim: Implement full Windows support with a PowerShell helper plus docs.

1. Add setup.ps1.

   • Mirror setup.sh functionality.
   • Use param([Parameter(Mandatory=$true)][string]$Example, [switch]$Run).
   • Use $PSScriptRoot for repo root.
   • Prefer python, fallback to py -3 if needed.
   • Validate Python version is at least 3.10.
   • Use venv-local Python executable for pip installs and optional run.
   • Preserve .env safety behavior.
   • Detect entry files in the same order as setup.sh.

2. Validate setup.ps1 syntax.

   • If pwsh exists, parse it using PowerShell parser.
   • If not, document that local syntax validation was unavailable.

3. Update README.md.

   • Add Windows PowerShell quickstart.
   • Add automated setup examples for both:
     • ./setup.sh fetch-hackathon-quickstarter
     • .\setup.ps1 fetch-hackathon-quickstarter
   • Mention process-scoped execution policy bypass only as troubleshooting.
   • Update repository tree to list setup.ps1.
   • Add PowerShell Docker Compose env var syntax.

4. Update CONTRIBUTING.md.

   • Mention Windows PowerShell helper alongside setup.sh.

5. Update CHANGELOG.md.

   • Add an [Unreleased] -> Added bullet for setup.ps1 and Windows setup docs.

6. Run:

   • git diff --check
   • PowerShell parser command if available.

Tradeoff:

• More complete and best aligned with “Windows-friendly setup path.”
• Higher risk because new PowerShell script needs syntax/runtime correctness and changelog update.

Risks

• PowerShell may not be installed in the local validation environment, limiting script verification.
• PowerShell execution policy can block setup.ps1; docs must avoid recommending permanent/global policy changes.
• Python launcher behavior differs across Windows installs:
  • some users have python,
  • some use py -3,
  • some may not have Python on PATH.
• A new setup.ps1 must avoid overwriting .env, matching setup.sh.
• Running example agents may require API keys, so automated runtime validation should not assume agents can fully start.
• README currently references root docker-compose.yml, but the provided file tree summary does not show one; avoid unrelated Docker cleanup unless directly needed for Windows command syntax.
• If only docs are changed, maintainers may request the actual setup.ps1 helper in review.
• If setup.ps1 is added but CHANGELOG.md is not updated, PR CI’s changelog-check should fail.

Candidate Race

Coder A

• Strategy: Minimal Safe Fix
• Branch: pr-factory/169-e58abg72-coder-a
• Diffstat:

CONTRIBUTING.md |  2 +-
 README.md       | 37 +++++++++++++++++++++++++++++++++++--
 2 files changed, 36 insertions(+), 3 deletions(-)

Summary

Implemented the minimal safe Windows setup fix and committed it locally.

Commit: 492dcfd docs: add Windows PowerShell quickstart

Files Changed

• README.md

  • Split root quickstart into:
    • macOS/Linux/Git Bash/WSL
    • Windows PowerShell
  • Added native PowerShell commands for:
    • cloning and entering the repo
    • selecting fetch-hackathon-quickstarter
    • creating and activating .venv
    • installing requirements
    • copying .env.example to .env
    • running the example
  • Clarified setup.sh is Bash-only and not intended for native Windows PowerShell.
  • Updated repository structure description for setup.sh.
  • Added Docker Compose PowerShell equivalent:
    • $env:EXAMPLE="fetch-hackathon-quickstarter"; docker compose up

• CONTRIBUTING.md

  • Clarified ./setup.sh <example-folder> is for macOS/Linux/Git Bash/WSL.
  • Pointed native Windows PowerShell users to the README PowerShell quickstart.

Why This Fix

This follows the requested “Minimal Safe Fix” strategy:

• Avoids adding a new setup.ps1, reducing script/runtime risk.
• Keeps existing macOS/Linux behavior unchanged.
• Makes the root setup path directly usable by native Windows PowerShell users through explicit manual commands.
• Avoids changelog requirements because the change is Markdown-only and CI skips changelog checks for doc-only PRs.

Tests Run

• git diff --check

Result: passed.

Also reviewed the relevant rendered Markdown sections in README.md and CONTRIBUTING.md.

Risks

• No setup.ps1 helper was added, so Windows users use documented manual PowerShell steps rather than an automated script.
• Maintainers may prefer the more comprehensive helper-script approach in review, but the issue explicitly allows making the setup instructions clearly cross-platform.
• PowerShell commands were documentation-reviewed but not executed on Windows from this macOS worktree.

Coder B

• Strategy: Test-First Comprehensive Fix
• Branch: pr-factory/169-e58abg72-coder-b
• Diffstat:

CHANGELOG.md                   |   1 +
 CONTRIBUTING.md                |   2 +-
 README.md                      |  51 +++++++++++-
 setup.ps1                      | 171 +++++++++++++++++++++++++++++++++++++++++
 tests/test_setup_ps1_static.py |  39 ++++++++++
 5 files changed, 261 insertions(+), 3 deletions(-)

Summary

Fresh ad-hoc verification completed successfully. No new edits were made.

Committed change remains:

e6521c8 Add Windows PowerShell setup helper

Files Changed

• setup.ps1
• tests/test_setup_ps1_static.py
• README.md
• CONTRIBUTING.md
• CHANGELOG.md

Why This Fix

Adds a native Windows PowerShell setup path while preserving the existing Bash helper and macOS/Linux/Git Bash/WSL docs.

Tests Run

Ad-hoc verification only, not a full suite-green claim.

Temporary verifier created:

/var/folders/yf/3mgk15tx2sj0zt3dm420wlb00000gn/T/hermes-verify-jvuyuexq.py

Command run:

python3 /var/folders/yf/3mgk15tx2sj0zt3dm420wlb00000gn/T/hermes-verify-jvuyuexq.py

Verifier checked:

• setup.ps1 required fragments and behavior guards:
  • [string]$Example
  • [switch]$Run
  • $PSScriptRoot
  • example folder validation
  • Python 3.10+ check
  • python plus py -3 fallback
  • .venv creation
  • venv-local Scripts\python.exe
  • requirements.txt install path
  • safe .env.example copy only when .env is absent
  • entry file order: agent.py, main.py, workflow.py, app.py
  • PowerShell activation hint
  • -Run execution branch
• python3 -m py_compile tests/test_setup_ps1_static.py
• python3 -m unittest discover -s tests -v
• git diff --check HEAD~1..HEAD

Result:

RESULT: passed

Cleanup:

CLEANED_UP=/var/folders/yf/3mgk15tx2sj0zt3dm420wlb00000gn/T/hermes-verify-jvuyuexq.py

Git status from verifier:

## pr-factory/169-e58abg72-coder-b...origin/main [ahead 1]

Risks

• PowerShell is not installed locally, so this remains static/ad-hoc verification plus Python regression tests, not an actual setup.ps1 runtime execution in PowerShell.

Judge Verdict

Winner: coder-b

Verdict

Winner: coder-b

Scorecard

Criterion	Coder A	Coder B	Notes
Correctness	8	9	A satisfies the manual PowerShell path, but does not add the preferred Windows helper. B more fully satisfies the planner spec by adding setup.ps1, docs, changelog, and contributing updates.
Test coverage	5	8	A ran only git diff --check, which is acceptable for docs-only but limited. B ran git diff --check, Python static tests, and unittest discovery, though actual PowerShell parser/runtime validation was unavailable.
Minimality	9	7	A is very small and low-touch. B adds a helper script plus a static test file, which is broader than strictly necessary but aligned with the preferred implementation.
Maintainability	7	8	A leaves Windows users with manual steps only. B creates a reusable sibling helper mirroring setup.sh, but the new script/test increase maintenance surface.
Repo convention fit	8	9	Both follow README/CONTRIBUTING conventions. B also updates CHANGELOG.md as required for adding a non-Markdown file and documents both helper scripts clearly.
Risk	8	7	A has lower implementation risk because it is docs-only. B has higher script-risk and no real PowerShell execution validation, but mitigates with static checks and tests.

Why the Winner Won

Coder B is the better candidate for a real PR because it implements the preferred solution from the planner spec: a native Windows PowerShell setup helper.

It covers the key acceptance points:

• Adds setup.ps1.
• Supports an example folder argument.
• Supports optional -Run.
• Validates the example folder.
• Checks Python 3.10+ with python and py -3 fallback.
• Creates .venv.
• Installs requirements.txt when present.
• Copies .env.example only when .env is absent.
• Detects entry files in the same order as setup.sh.
• Prints PowerShell activation/run guidance.
• Updates README quickstart with clearly separated Bash and PowerShell instructions.
• Clarifies setup.sh vs setup.ps1.
• Adds Docker Compose PowerShell syntax.
• Updates CONTRIBUTING.md.
• Updates CHANGELOG.md, which is required because a non-Markdown file was added.
• Adds static regression coverage for the new script behavior.

The main limitation is that PowerShell itself was not available locally, so the script was not parsed or executed by pwsh. Still, relative to the issue, B is substantially more complete and better aligned with the preferred path.

Why the Other Candidate Lost

Coder A is a safe and reasonable minimal documentation fix, but it is less complete.

Strengths:

• Keeps scope very small.
• Avoids script/runtime risk.
• Clearly documents native Windows PowerShell manual setup.
• Clarifies that setup.sh is Bash-only.
• Adds the Docker Compose PowerShell equivalent.
• Avoids changelog requirements by staying Markdown-only.

Why it loses:

• It does not add the preferred setup.ps1 helper.
• Windows users still need to manually translate the automated setup flow into several commands.
• The repository remains asymmetric: Bash users get automation, native PowerShell users get docs only.
• Maintainers are more likely to prefer B because the planner explicitly identifies setup.ps1 as the preferred implementation.

Coder A would be acceptable if the maintainers wanted the smallest possible docs-only fix, but B is stronger for a real PR against the stated issue.

Required QA Checks

Before merging Coder B, run:

• git diff --check
• If PowerShell is available:
  • pwsh -NoProfile -Command '$null = [System.Management.Automation.Language.Parser]::ParseFile("setup.ps1", [ref]$null, [ref]$errors); if ($errors.Count) { $errors | Format-List; exit 1 }'
• Ideally on Windows or a Windows CI runner:
  • .\setup.ps1 fetch-hackathon-quickstarter
  • Re-run with an existing .env and confirm it is not overwritten.
  • Confirm .\setup.ps1 fetch-hackathon-quickstarter -Run invokes the detected entry file.
• Confirm README code fences render correctly.
• Confirm CHANGELOG.md placement under [Unreleased] -> Added matches repo convention.
• Review whether tests/test_setup_ps1_static.py fits the repository’s test conventions or should be simplified/omitted if the repo does not normally test helper scripts.

Memory to Save

No durable repo memory needs to be saved.

QA Result

QA Verdict

APPROVED

Tests

• git diff --check: passed.
• Metadata reports testsPassed: true.
• No failing test output was provided.
• Note: PowerShell parser/runtime validation was recommended but not included in the provided test command output.

Acceptance Criteria Check

• README now includes explicit native Windows PowerShell setup instructions for cloning, selecting an example, creating/activating a venv, installing requirements, copying .env.example, and running the example.
• README clearly separates macOS/Linux/Git Bash/WSL Bash commands from Windows PowerShell commands.
• Added setup.ps1, providing the preferred Windows-friendly automated setup path.
• README documents setup.sh as the Bash/macOS/Linux/Git Bash/WSL helper and setup.ps1 as the Windows PowerShell helper.
• setup.ps1 appears to satisfy the required behavior:
  • accepts example folder argument,
  • supports optional -Run,
  • validates example folder existence,
  • checks Python 3.10+ with python and py -3 fallback,
  • creates .venv,
  • installs requirements.txt if present,
  • copies .env.example only when .env is absent,
  • detects entry files in the same order as setup.sh,
  • prints PowerShell-appropriate activation/run instructions.
• Docker Compose README instructions now include a PowerShell equivalent for setting EXAMPLE.
• CONTRIBUTING.md mentions the PowerShell helper.
• CHANGELOG.md was updated under [Unreleased] -> Added, which is required because setup.ps1 is a new non-Markdown file.

Risks

• setup.ps1 was not validated with pwsh in the provided test output, so PowerShell syntax/runtime issues remain possible.
• The new tests/test_setup_ps1_static.py is lightweight static coverage only and was not part of the provided configured test command.
• Actual Windows behavior, execution policy handling, and .env preservation should ideally be validated on a Windows runner before merge, but this is not a blocker for opening the PR.

Final PR Notes

This PR is safe to open. It addresses the planner’s acceptance criteria, includes the preferred PowerShell helper implementation, updates the required docs and changelog, and passes the provided configured validation command.

Tests

git diff --check

Memory Used

(No repo memory used.)

Run Metrics

• Run ID: jh75sahasdh9d6kkrzzt23r2e58abg72
• Total duration: 538s
• Estimated cost: $0.0000
• Repo Researcher model: gpt-5.5
• Planner model: gpt-5.5
• Coder A model: gpt-5.5
• Coder B model: gpt-5.5
• Judge model: gpt-5.5
• QA model: gpt-5.5

Decision Trail

Full run trace is available in PR Factory dashboard.