docs: update documentation for smoke tests and CI automation

.context/docs/development-workflow.md

@@ -0,0 +1,52 @@
+---
+type: doc
+name: development-workflow
+description: Day-to-day engineering processes, branching, and contribution guidelines
+category: workflow
+generated: 2026-07-29
+status: filled
+---
+
+# Development Workflow
+
+## Prerequisites
+
+- Docker
+- Git
+
+## Local Development
+
+1. Clone the repository
+2. Build the Docker image:
+   ```bash
+   docker compose build
+   ```
+3. Run the full smoke test suite:
+   ```bash
+   tests/smoke_build.sh && tests/smoke_ansible.sh && tests/smoke_python.sh && tests/smoke_shell.sh && tests/smoke_playbook.sh
+   ```
+4. Or test a single command:
+   ```bash
+   docker run --rm eftechcombr/ansible-cli-github-action "ansible --version"
+   ```
+
+## Making Changes
+
+- Edit the appropriate file (`Dockerfile`, `entrypoint.sh`, `requirements.txt`, `action.yml`)
+- Rebuild and run the smoke test suite locally
+- Update `README.md` if the interface changes
+- Verify all five smoke tests pass before committing
+
+## CI/CD
+
+The repository has two workflows (see `.github/workflows/`):
+
+- **test.yaml** — Runs automatically on every push (any branch) and pull request (targeting master). Executes all five smoke tests: build, ansible CLI, Python imports, shell passthrough, and playbook execution. Can also be triggered manually via `workflow_dispatch`.
+- **build.yaml** — Manually triggered workflow that builds the Docker image using `docker/build-push-action` (no push).
+
+## Contribution Guidelines
+
+- Follow conventional commits for PR titles
+- Test changes locally with the full smoke test suite
+- Ensure all five smoke tests pass
+- Update `README.md` for any interface or input changes

.context/docs/testing-strategy.md

@@ -0,0 +1,78 @@
+---
+type: doc
+name: testing-strategy
+description: Test frameworks, patterns, coverage requirements, and quality gates
+category: testing
+generated: 2026-07-29
+status: filled
+---
+
+# Testing Strategy
+
+## Approach
+
+This project is a thin Docker-based GitHub Action. Testing focuses on three areas:
+
+1. **Container build** — ensure the Docker image builds successfully
+2. **Command execution** — verify that Ansible is installed and runnable inside the container
+3. **Runtime behavior** — verify shell passthrough, exit code propagation, and playbook execution
+
+Smoke tests are implemented as standalone shell scripts in `tests/` that can be run locally or in CI.
+
+## Tests
+
+### Local Testing
+
+Build the image first, then run the full smoke test suite:
+
+```bash
+tests/smoke_build.sh && tests/smoke_ansible.sh && tests/smoke_python.sh && tests/smoke_shell.sh && tests/smoke_playbook.sh
+```
+
+Individual smoke tests can also be run independently:
+
+```bash
+tests/smoke_build.sh            # must run first — sets image tag
+tests/smoke_ansible.sh          # checks ansible, ansible-playbook, ansible-inventory
+tests/smoke_python.sh           # checks Python dependency imports (winrm, ansible)
+tests/smoke_shell.sh            # checks eval passthrough and exit code propagation
+tests/smoke_playbook.sh         # checks playbook syntax checking and localhost ping
+```
+
+Alternatively, build and test with Docker Compose:
+
+```bash
+docker compose build
+docker run --rm eftechcombr/ansible-cli-github-action "ansible --version"
+```
+
+### CI Testing (GitHub Actions)
+
+The workflow in `.github/workflows/test.yaml` runs all five smoke tests automatically on every push (any branch) and pull request (targeting master). It can also be triggered manually via `workflow_dispatch`.
+
+The CI pipeline executes the same checks as the local smoke scripts:
+
+- **smoke_build** — verifies the Docker image is built
+- **smoke_ansible** — runs `ansible --version`, `ansible-playbook --version`, `ansible-inventory --help`
+- **smoke_python** — imports `winrm` and `ansible` Python packages
+- **smoke_shell** — verifies command output passthrough and exit code propagation
+- **smoke_playbook** — runs `ansible-playbook --syntax-check` and a ping playbook against localhost
+
+## Quality Gates
+
+- Docker image must build without errors
+- `ansible --version` must exit with code 0
+- `ansible-playbook --version` must exit with code 0
+- `ansible-inventory --help` must exit with code 0
+- Python `winrm` and `ansible` module imports must succeed
+- Shell command output must pass through correctly
+- Shell exit codes must propagate correctly
+- Playbook syntax checking must pass
+- Playbook must run successfully against localhost with the `local` connection plugin
+
+## What We Don't Test
+
+- Ansible playbook correctness (the action is a runner, not a linter)
+- Specific Ansible modules or features (upstream Ansible tests those)
+- Remote host connectivity or SSH configuration
+- Multi-node playbook orchestration

.context/docs/tooling.md

@@ -0,0 +1,75 @@
+---
+type: doc
+name: tooling
+description: Scripts, IDE settings, automation, and developer productivity tips
+category: tooling
+generated: 2026-07-29
+status: filled
+---
+
+# Tooling
+
+## Docker Compose
+
+`docker-compose.yaml` provides a quick way to build and tag the image:
+
+```bash
+docker compose build
+```
+
+## VS Code Settings
+
+`.vscode/settings.json` contains:
+
+```json
+{
+    "kiroAgent.configureMCP": "Enabled"
+}
+```
+
+## GitHub Actions
+
+The CI workflow runs automatically:
+
+- **Test** (`.github/workflows/test.yaml`) — triggered on every push (any branch) and pull request (targeting master). Runs all five smoke tests: build, ansible CLI, Python imports, shell passthrough, and playbook execution. Also supports manual trigger via `workflow_dispatch`.
+- **Build** (`.github/workflows/build.yaml`) — manually triggered workflow that builds the Docker image using `docker/build-push-action` (no push to registry).
+
+## Smoke Tests
+
+Five standalone shell scripts live in `tests/`:
+
+| Script | What It Tests |
+|---|---|
+| `smoke_build.sh` | Docker image builds successfully |
+| `smoke_ansible.sh` | Ansible CLI tools are present and runnable |
+| `smoke_python.sh` | Python dependencies (`winrm`, `ansible`) are importable |
+| `smoke_shell.sh` | Command passthrough and exit code propagation |
+| `smoke_playbook.sh` | Playbook syntax checking and localhost execution |
+
+Run the full suite:
+
+```bash
+tests/smoke_build.sh && tests/smoke_ansible.sh && tests/smoke_python.sh && tests/smoke_shell.sh && tests/smoke_playbook.sh
+```
+
+## Quick Reference
+
+```bash
+# Build locally
+docker compose build
+# or
+docker build -t ansible-cli-smoke:test .
+
+# Run all smoke tests
+tests/smoke_build.sh && tests/smoke_ansible.sh && tests/smoke_python.sh && tests/smoke_shell.sh && tests/smoke_playbook.sh
+
+# Run a command
+docker run --rm eftechcombr/ansible-cli-github-action "ansible --version"
+
+# Interactive shell (for debugging)
+docker run --rm -it --entrypoint /bin/bash eftechcombr/ansible-cli-github-action
+```
+
+## No Package Manager
+
+This project has no `package.json` — all dependencies are Python-based and managed via `requirements.txt`.

.github/workflows/test.yaml

@@ -1,18 +1,54 @@
-name: Run 
+name: Smoke tests
 
 on:
-  workflow_dispatch: 
-    inputs:
-      command:
-        description: "Command to execute"
-        required: true
-        default: "ansible-playbook"
-
-jobs: 
-  run: 
+  push:
+    branches: ["**"]
+  pull_request:
+    branches: ["master"]
+  workflow_dispatch:
+
+jobs:
+  smoke:
     runs-on: ubuntu-latest
-    steps: 
-      - uses: eftechcombr/ansible-cli-github-action@master
-        with:
-          command: "ansible --version"
-
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build Docker image
+        run: docker build -t ansible-cli-smoke:test .
+
+      - name: smoke_build — image built
+        run: docker image inspect ansible-cli-smoke:test > /dev/null
+
+      - name: smoke_ansible — CLI version checks
+        run: |
+          docker run --rm ansible-cli-smoke:test "ansible --version"
+          docker run --rm ansible-cli-smoke:test "ansible-playbook --version"
+          docker run --rm ansible-cli-smoke:test "ansible-inventory --help"
+
+      - name: smoke_python — dependency imports
+        run: |
+          docker run --rm ansible-cli-smoke:test "python -c 'import winrm; print(\"winrm ok\")'"
+          docker run --rm ansible-cli-smoke:test "python -c 'import ansible; print(\"ansible ok\")'"
+
+      - name: smoke_shell — eval passthrough
+        run: |
+          OUTPUT=$(docker run --rm ansible-cli-smoke:test "echo hello from ansible")
+          [ "$OUTPUT" = "hello from ansible" ] || { echo "FAIL: $OUTPUT"; exit 1; }
+
+      - name: smoke_shell — exit code propagation
+        run: |
+          set +e
+          docker run --rm ansible-cli-smoke:test "exit 42"
+          RC=$?
+          set -e
+          [ "$RC" -eq 42 ] || { echo "FAIL: expected 42, got $RC"; exit 1; }
+
+      - name: smoke_playbook — syntax check
+        run: |
+          docker run --rm -v ${{ github.workspace }}/tests:/tests:ro ansible-cli-smoke:test \
+            "ansible-playbook --syntax-check /tests/test.yml"
+
+      - name: smoke_playbook — ping localhost
+        run: |
+          docker run --rm -v ${{ github.workspace }}/tests:/tests:ro ansible-cli-smoke:test \
+            "ansible-playbook -i 'localhost,' -c local /tests/test.yml"

AGENTS.md

@@ -0,0 +1,30 @@
+# AGENTS.md
+
+## Dev environment tips
+- Build the Docker image with `docker build -t ansible-cli-smoke:test .` before running tests.
+- Use `docker compose build` for the Compose-based build.
+
+## Testing instructions
+- Run all smoke tests: `tests/smoke_build.sh && tests/smoke_ansible.sh && tests/smoke_python.sh && tests/smoke_shell.sh && tests/smoke_playbook.sh`
+- Or run individual tests: `tests/smoke_build.sh` (must run first — sets image tag), then any of `tests/smoke_ansible.sh`, `tests/smoke_python.sh`, `tests/smoke_shell.sh`, `tests/smoke_playbook.sh`
+- CI runs all smoke tests via `.github/workflows/test.yaml` on every push and PR.
+
+## PR instructions
+- Follow Conventional Commits (for example, `feat(scaffolding): add doc links`).
+- Cross-link new scaffolds in `docs/README.md` and `agents/README.md` so future agents can find them.
+- Attach sample CLI output or generated markdown when behaviour shifts.
+- Confirm the built artefacts in `dist/` match the new source changes.
+
+## Repository map
+- `action.yml` — GitHub Action metadata (inputs, branding, Docker runtime config)
+- `docker-compose.yaml` — local dev convenience for building and tagging the image
+- `Dockerfile` — builds the container from `python:3.11-slim`
+- `entrypoint.sh` — container entrypoint, executes `eval $1`
+- `README.md` — user-facing documentation
+- `requirements.txt` — Python dependencies (`ansible`, `pywinrm[credssp]`)
+- `tests/` — smoke test scripts and test fixtures
+
+## AI Context References
+- Documentation index: `.context/docs/README.md`
+- Agent playbooks: `.context/agents/README.md`
+- Contributor guide: `CONTRIBUTING.md`

README.md

@@ -1,8 +1,8 @@
 # Ansible CLI Github Action
 
-This action is based on `ubuntu:bionic` image.  
-You can execute all `Ansible` related actions i.e, `ansible` or `ansible-playbook`.  
-You can also execute standard `Linux` commands as base `Docker` image is `ubuntu`.
+This action is based on the `python:3.11-slim` image.  
+You can execute all Ansible-related commands: `ansible`, `ansible-playbook`, `ansible-galaxy`, and others.  
+You can also execute standard Linux commands as the base image includes a shell environment.
 
 ## Inputs
 
@@ -12,8 +12,26 @@ You can also execute standard `Linux` commands as base `Docker` image is `ubuntu
 
 ## Example usage
 
-```
-uses: actions/ansible-cli-action@latest
+```yaml
+uses: eftechcombr/ansible-cli-github-action@latest
 with:
   command: "ansible-playbook main.yml"
 ```
+
+## Testing
+
+Run the smoke test suite locally to verify the Docker image builds and all Ansible tools work correctly:
+
+```bash
+tests/smoke_build.sh && tests/smoke_ansible.sh && tests/smoke_python.sh && tests/smoke_shell.sh && tests/smoke_playbook.sh
+```
+
+The smoke tests cover:
+
+- Docker image build
+- Ansible CLI version checks (`ansible`, `ansible-playbook`, `ansible-inventory`)
+- Python dependency imports (`winrm`, `ansible`)
+- Shell command passthrough and exit code propagation
+- Playbook syntax checking and localhost execution
+
+CI runs these tests automatically on every push and pull request via GitHub Actions.

tests/smoke_ansible.sh

@@ -0,0 +1,17 @@
+#!/bin/sh
+set -e
+
+. /tmp/ansible_smoke_image 2>/dev/null || IMG_LABEL="ansible-cli-smoke:test"
+
+echo "=== smoke_ansible: Ansible CLI tools ==="
+
+echo "  -> ansible --version"
+docker run --rm "$IMG_LABEL" "ansible --version"
+
+echo "  -> ansible-playbook --version"
+docker run --rm "$IMG_LABEL" "ansible-playbook --version"
+
+echo "  -> ansible-inventory --help"
+docker run --rm "$IMG_LABEL" "ansible-inventory --help"
+
+echo "PASS: smoke_ansible"

tests/smoke_build.sh

@@ -0,0 +1,11 @@
+#!/bin/sh
+set -e
+
+echo "=== smoke_build: Docker image build ==="
+
+IMG_LABEL="ansible-cli-smoke:test"
+
+docker build -t "$IMG_LABEL" .
+
+echo "PASS: smoke_build"
+echo "IMG_LABEL=$IMG_LABEL" > /tmp/ansible_smoke_image

tests/smoke_playbook.sh

@@ -0,0 +1,17 @@
+#!/bin/sh
+set -e
+
+. /tmp/ansible_smoke_image 2>/dev/null || IMG_LABEL="ansible-cli-smoke:test"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+echo "=== smoke_playbook: Ansible playbook parsing and local run ==="
+
+echo "  -> syntax check"
+docker run --rm -v "$SCRIPT_DIR:/tests:ro" "$IMG_LABEL" \
+  "ansible-playbook --syntax-check /tests/test.yml"
+
+echo "  -> ping localhost"
+docker run --rm -v "$SCRIPT_DIR:/tests:ro" "$IMG_LABEL" \
+  "ansible-playbook -i 'localhost,' -c local /tests/test.yml"
+
+echo "PASS: smoke_playbook"