Isolated and portable "ready-to-prompt" environment for the Gentle AI ecosystem
Documentation: English
It provides a preconfigured, cross-platform, extensible, and replicable "ready-to-prompt" environment for starting AI projects in an orderly way: understand the goal, clarify requirements, use SDD/OpenSpec/ODD artifacts, apply skills, coordinate subagents, implement in phases — discover > research > design > plan > implement > verify — and iterate until the expected results are achieved.
The project on this branch is the producer designed to provide a clean baseline
structure before starting a new project or integrating it with an existing project.
As a consumer, you should clone the starter branch and create the remote upstream
for future upgrades. These are core files:
.
├── .agents
│ └── skills
│ └── add-tool/
├── .devcontainer/
├── .taskfiles/
├── .env.d/
├── .markdownlint-cli2.yaml
└── Taskfile.ymlThe complete structure is mentioned here
The environment combines mandatory core tools with opt-in catalog tools and integrations—not everything below is installed by default.
- OpenCode as the default assisted-development interface.
- Pi Coding Agent as an opt-in alternative extensible harness (disabled by default).
- Gentle AI for managed AI workflows alongside OpenCode, included in the mandatory core.
- Engram as local persistent memory inside the environment.
- Dev Container based on Ubuntu 24.04.
- Taskfile to centralize common commands.
You can activate catalog tools or add your own installers, with or without AI. See
the install layout and cache boundaries.
Run task install:list for the current catalog and activation state.
Supporting tools and optional extensions list: 👇🏼
| Tool | Purpose |
|---|---|
| Node.js | Run JavaScript programs and command-line development tools |
| npm | Install, publish, and manage JavaScript package dependencies |
| pnpm | Install and manage packages with a fast, workspace-aware workflow |
| Go | Compile and run Go applications and developer tools |
| Java 25 | Run and build JVM applications with the optional toolchain |
| SDKMAN | Install and switch between Java SDK versions per environment |
| Temurin | Provide the default OpenJDK distribution for Java development |
| PHP | Run PHP applications and command-line scripts |
| Composer | Install and manage PHP application dependencies |
| Tool | Purpose |
|---|---|
| Bats | Exercise shell scripts with readable Bash test cases |
| PHPUnit | Run unit and integration tests for PHP code |
| Xdebug | Inspect PHP execution with breakpoints and runtime diagnostics |
| Vitest | Run fast JavaScript and TypeScript unit tests |
| Delve | Debug Go programs with breakpoints and stack inspection |
| Playwright | Automate browser scenarios for end-to-end testing |
| Chromium | Provide a browser runtime for automated test sessions |
| @playwright/cli | Control browser sessions from agent workflows |
| Tool | Purpose |
|---|---|
| Context7 | Retrieve current library documentation through MCP requests |
| markdownlint-cli2 | Check Markdown style and formatting in documentation |
| Glow | Read and preview Markdown directly in a terminal |
| Spectral CLI | Lint API descriptions against reusable quality rules |
| Redocly CLI | Validate, bundle, and preview OpenAPI descriptions |
| AsyncAPI CLI | Validate and work with event-driven API descriptions |
| Mermaid CLI | Render text-defined diagrams for documentation and reviews |
| Archify | Explore interactive diagrams for software architecture |
| Graphviz | Generate graphs from structured relationships and data |
| PlantUML | Create diagrams from concise text-based definitions |
| C4-PlantUML | Model software architecture with C4 diagram conventions |
| Graphify | Build and inspect knowledge graphs from connected concepts |
| Graphify MCP | Expose graph operations to MCP-compatible clients |
| Tool | Purpose |
|---|---|
| Docker Compose | Build and run isolated application containers |
| OpenSSH | Connect to hosts and provide secure remote shell access |
| Ansible Core | Automate repeatable configuration and deployment tasks |
| kubectl | Inspect and manage resources in Kubernetes clusters |
| Terraform | Define and provision infrastructure from declarative configuration |
| OpenTofu | Provision infrastructure with an open-source declarative workflow |
| Terragrunt | Coordinate reusable infrastructure configurations and deployments |
| Pulumi | Provision cloud resources using general-purpose languages |
| Gitleaks | Scan repositories for accidentally committed secrets |
| Tool | Purpose |
|---|---|
| Skills CLI | Install and update reusable agent skills |
| Gentleman Guardian Angel (GGA) | Provide image-installed review tooling; project setup and Git hooks are optional manual steps |
| Gentle Pi | Extend Pi workflows with Gentle AI integrations |
| Pi Subagents | Run delegated Pi tasks through reusable subagent support |
| Pi Intercom | Exchange messages between Pi workflows and agents |
| Pi Web Access | Give Pi workflows controlled access to web resources |
| Pi Lens | Provide real-time feedback while reviewing code changes |
| RPIV Todo | Track implementation tasks within Pi workflows |
| RPIV Ask User Question | Collect structured answers from users during Pi workflows |
| RPIV BTW | Handle side questions without interrupting the main task |
| Gentle Engram | Connect Pi workflows to persistent project memory |
| Pi MCP Adapter | Connect Pi to MCP servers and their tools |
| Pi Terminal Theme | Customize terminal appearance for Pi sessions |
| Tool | Purpose |
|---|---|
| PulseAudio | Provide optional audio playback clients such as paplay |
Versioned skills provide a customizable base: external packages are tracked in
skills-lock.json; repository-authored skills live in .agents/skills/ and are
tracked by Git. Host audio integration is separate from audio clients.
On your PC host, install current stable releases:
- Git
- Task
- Docker
- Dev Container CLI
- jq
- yq — Mike Farah yq v4 is recommended; volume discovery also supports Kislyuk yq.
- Python 3
An IDE is optional and does not replace these host requirements.
attach to running container is the only supported method.
-
On your PC host:
git clone --branch starter --origin upstream https://github.com/Cesarucho/gentle-starter.git <my-project> cd <my-project> git branch -m main git branch --unset-upstream cp .env.example .env
Add your project remote when ready:
git remote add origin <your-project-url>.Already have a project? Follow the existing-project integration guide.
Use the terminal workflow below. For the container life cycle only, Task is
the supported entry point (build, create, run, stop, remove, restart, and more);
an IDE may only attach after task container:up.
-
In your PC host terminal, from the project directory, run:
task container:up # it will build the image if needed # choose a "connect" method: task container:connect # interactive terminal with bash task container:opencode # directly to the ai-agent application
-
If you chose
container:connect, use any tool normally:git status engram --version gentle-ai --version opencode --version opencode auth login # choose and authenticate a provider opencode -c # open the ai-agent from the last session.
-
If you chose
container:opencodeor executedopencode -cinside of container, you can start with:choose and authenticate a provider
❯_ /connect
configure the models
❯_ /sdd-models
It is recommended to automate your own profiles, details in Tool Configurations
and prompting, examples:
❯_ Use "add-tool" skill for add PostgreSQL-16 with a version-controlled `pg_hba.conf` and persistent data volume.
- Install IDE, for example VS Code and its Dev Containers extension on your host.
- Run
task container:upfrom the project directory in your host terminal, it can be the IDE terminal too. - In VS Code's Command Palette (
ctrl + shift + p), runDev Containers: Attach to Running Container...and choose this project's running container. - Use File > Open Folder... to open the actual workspace inside the
container:
/home/ubuntu/<project-name>.
Do not use the IDE's Reopen in Container or Rebuild Container actions.
These creation paths are unsupported because they bypass Task's host
preparation. From your host terminal, use task container:recreate to replace
the container, or task container:rebuild && task container:up to rebuild
the software and start it. Then attach VS Code again.
Clones of the published starter branch share its linear release ancestry, so
updates use ordinary Git. This does not mean starter descends from the producer
dev branch. The clone already has upstream. From your branch, fetch and merge
the consumer branch:
git fetch upstream
git merge upstream/starterResolve merge conflicts manually and commit the resolution normally. Existing
origin and branch upstream settings remain under project-owner control.
task tools:update # From inside container, update the repository's approved version policy
git diff # Review user intent and generated locks together
task container:rebuild # From host, remove the container and build the updated image
task container:up # From host, create/start the updated development environment
task validate # Inside container: diagnosis and strict qualityEdit only TOOL_*_VERSION fields. tools:update alone resolves stable exact versions,
generates checksums, and atomically replaces the policy without updating installed tools.
Builds and installers are read-only; rebuild then run up to apply, and commit after verification. See ADR 0003.
If GitHub rate limits anonymous discovery, use an existing GitHub CLI authentication explicitly:
TOOLS_UPDATE_USE_GH_AUTH=1 task tools:updateThe opt-in is limited to github.com. A non-empty GH_TOKEN takes precedence;
otherwise the opt-in resolves gh auth token for github.com. GitHub REST
discovery responses are regenerated in the private local cache at
${XDG_CACHE_HOME:-$HOME/.cache}/gentle-starter/tools-update/github-api/ and
use ETags to avoid unchanged requests.
-
OpenCode profiles
You can configure each "sdd-*" sub-agent with the model and effort to your liking (command:
/sdd-model); these preferences are saved in runtime files~/.config/opencode/opencode.jsonand~/.config/opencode/profiles/which you can then export to default preferencestask config:export:.devcontainer/config/opencode ├── opencode.json └── profiles/ ├── openai-100usd-astral.json └── openai-20usd-pareto.jsonCurrently, opencode has the
openai-20usd-paretoprofile configured. -
Keep your preferences as the default setting.
Runtime files are the source of truth. Once the container is created, the configuration files are copied to runtime directories:
.devcontainer/config/opencode → /home/ubuntu/.config/opencode .devcontainer/config/pi → /home/ubuntu/.pi
But during normal use, we often change our preferences; if we want to keep them as a base, we export them as part of our repository structure, we can do this manually or using these commands:
task config:diff task config:export git diff -- .devcontainer/config # Review exactly what will be versionedconfig:exportcopies configuration in container runtime → repository directory direction:/home/ubuntu/.config/opencode → .devcontainer/config/opencode /home/ubuntu/.pi → .devcontainer/config/piThe
.devcontainer/config-export.jsonfile manages exports. When you need to add a new configuration from another tool (such as pg_hba.conf for PostgreSQL), remember to request it from the ai-agent using theadd-toolskill.See Configuration for the complete contract.
# On the host: required prerequisites and snapshot diagnostics (partial proof)
# Inside the container: environment diagnosis and strict ShellCheck, shfmt, Markdown lint
task validate
# Application tests: configure tasks.test.cmds in Taskfile.yml first
task testThere is a catalog of standardized tools that can be enabled from
.devcontainer/install/available/ to .devcontainer/install/03-enabled/.
task install:list
task install:enable -- 2300-php-lang # Enable by symlink
task install:disable -- 2300-php-lang # Remove the symlink
task install:doctor # Verify integrity
# For changes to take effect
task container:rebuild
task container:up# Container commands, only useful on your PC (outside the container)
task container:build # build without removing or starting the container
task container:up # create/start as needed; startup may build
task container:restart # restart the same existing running or stopped container
task container:recreate # remove then up; apply mount/environment changes
task container:rebuild # remove then build only; run up separately to start# These tasks auto-start the devcontainer if it is not running
task container:connect # open a shell; run `opencode` inside
task container:pi # connect to Pi using `pi --continue`
task container:engram # connect to the Engram TUI
task container:opencode # direct TUI using `opencode --continue`
task container:opencode:server # attach to a reused or task-owned OpenCode server
container:opencode:serverup the server mode, so you can connect from web-browser/application usinghttp://<ip>:<opencode_port>/address.
- ip can be:
localhost,127.0.0.1or LAN/WLAN IP.- opencode_port is calculated and found in the
.envfile.- Optional credentials can be configured in the
.envfile usingOPENCODE_SERVER_USERNAMEandOPENCODE_SERVER_PASSWORD.
The starter branch contains the reusable development environment without
maintainer identity or planning files. Its own release ancestry supports later
consumer merges; it does not include producer dev history.
.
├── .agents/
│ └── skills
│ └── add-tool/ * Unique local-installed skill
├── .devcontainer/ * Reusable development environment
│ ├── docs/ Guides
│ ├── install/ Installers core/opt tools
│ ├── lifecycle/ Internal helpers
│ ├── docker-compose.yml Dev Container service
│ ├── README.md Devcontainer-specific documentation
│ ├── setup.sh Post-create configuration
│ └── tool-versions.conf Centralized tool-version policy
├── .taskfiles/ * Task implementations
├── .env.d/ * Local environment state, details below section
├── .env.example
├── .gitattributes
├── .gitignore
├── .markdownlint-cli2.yaml
├── LICENSE
└── Taskfile.yml * Automation commands entry point
# (*) It's a main file or directory
⚠️ If you are integrating an existing project and any main file coincides (even if there is no conflict), considers that integration is not compatible.
The .env.example file documents safe local variables for creating your own
.env:
cp .env.example .envThe .env.d/ directory is intended to store local environment state and should not
be versioned. It is currently used to mount data such as:
.env.d/ Content <-- not versioned -->
├── .engram Local Engram database
│ ├── engram.db
│ ├── engram.db-shm
│ └── engram.db-wal
├── .gitconfig Local Git configuration inside the container
│ ├── config
│ └── .git-credentials
├── .opencode Local OpenCode application state
│ └── share/
├── .gentle-ai Local Gentle AI state
│ ├── backups/
│ ├── cache/
│ └── state.json
└── .pi Local Pi state and configuration
├── agent/
└── gentle-ai/
Important: do not commit tokens, credentials, or local databases to Git. The repository ignores
.env.d/,.env,.pi/, and.atl/to avoid publishing local state by accident.
Edit .devcontainer/install/01-foundation/10-system.sh to add packages installed with
apt during the image build.
Default configuration are in Dockerfile .devcontainer/Dockerfile, but you can
change it for each container instance from .env file, example:
LOCALE=es_MX.UTF-8
TZ=America/Mexico_CityAsk OpenCode to use the project add-tool skill. Describe the tool, version,
whether it should be enabled by default, and any configuration or persistent
state it needs.
For example, this request covers installation, version policy, configuration, and persistent data:
Add PostgreSQL 16 and enable it by default. Persist its data across container
recreations, add a version-controlled pg_hba.conf, and run the applicable tests.
For simpler requests or host integration, see the extension examples.
Use the earlier install catalog commands, or see Extending Gentle Starter for the manual architecture.
Run the installed skills CLI inside the container. External project skills are
recorded in skills-lock.json; add-tool is authored in this repository and
tracked by Git under .agents/skills/add-tool/, not in the external lock.
Use these commands for project skills:
skills list --json
skills add <source> --skill <name> --agent opencode --copy
skills update --project
skills remove <name>Remove only by explicit name. NEVER use wildcard removal or skills remove --all:
they can delete the Git-tracked add-tool skill. If add-tool was deleted accidentally, restore only
.agents/skills/add-tool/ from Git.
See the official Skills CLI documentation for more commands.
This starter uses Docker-in-Docker and elevated permissions for some development
flows. Do not publish .env, .env.d/, .pi/, or .atl/.