Merge pull request #22 from attogram/add-new-platforms

feat: Add comprehensive guides for multiple platforms

Author: attogram

.repo/AGENTS.md

@@ -27,6 +27,7 @@ This repository uses a specific structure to organize instructions. You must fam
 
 - **`../agents/`**: Contains technical instructions for specific AI agent personas (the "who").
 - **`../humans/`**: Contains guides for humans on how to interact with the AI agent personas.
+- **`../personas/`**: Contains personality traits and profiles that agents can adopt (the "how").
 - **`../platforms/`**: Contains technical instructions for how agents should work with specific technologies (the "what").
 
 ## Your Task

README.md

@@ -45,9 +45,23 @@ Standardize your AI collaboration.
 
 ## Platforms
 
-- [Bash](./platforms/bash.md) - for Bash
-- [PHP](./platforms/php.md) - for PHP
-- [PHP with Laravel](./platforms/php.laravel.md) - for PHP with Laravel
+- [Bash](./platforms/bash.md)
+- [C++](./platforms/cpp.md)
+- [Docker](./platforms/docker.md)
+- [Go](./platforms/go.md)
+- [JavaScript](./platforms/javascript.md)
+  - [Next.js](./platforms/javascript-nextjs.md)
+  - [Node.js](./platforms/javascript-nodejs.md)
+  - [React](./platforms/javascript-react.md)
+  - [Vue.js](./platforms/javascript-vue.md)
+- [PHP](./platforms/php.md)
+  - [Laravel](./platforms/php.laravel.md)
+  - [WordPress](./platforms/php-wordpress.md)
+- [PostgreSQL](./platforms/postgresql.md)
+- [Python](./platforms/python.md)
+  - [Django](./platforms/python-django.md)
+- [Rust](./platforms/rust.md)
+- [TypeScript](./platforms/typescript.md)
 
 ## Development
 

platforms/README.md

@@ -0,0 +1,19 @@
+# Platforms
+
+- [Bash](./bash.md)
+- [C++](./cpp.md)
+- [Docker](./docker.md)
+- [Go](./go.md)
+- [JavaScript](./javascript.md)
+  - [Next.js](./javascript-nextjs.md)
+  - [Node.js](./javascript-nodejs.md)
+  - [React](./javascript-react.md)
+  - [Vue.js](./javascript-vue.md)
+- [PHP](./php.md)
+  - [Laravel](./php.laravel.md)
+  - [WordPress](./php-wordpress.md)
+- [PostgreSQL](./postgresql.md)
+- [Python](./python.md)
+  - [Django](./python-django.md)
+- [Rust](./rust.md)
+- [TypeScript](./typescript.md)

platforms/cpp.md

@@ -0,0 +1,113 @@
+# Working with C++
+
+This document provides guidelines and best practices for AI agents working on C++ projects. The focus is on **Modern C++ (C++11 and newer)**, which introduced features that make the language safer, more expressive, and easier to use.
+
+## 1. Development Environment
+
+A C++ project requires a compiler, a build system, and often a package manager.
+
+### Compilers
+
+- **GCC (GNU Compiler Collection)**: The `g++` compiler is the standard on most Linux systems.
+- **Clang**: A modern compiler from the LLVM project, known for its excellent error messages.
+- **MSVC**: The Microsoft Visual C++ compiler, standard on Windows.
+
+### Build Systems
+
+**CMake** is the de-facto standard build system for modern C++ projects. It uses a script named `CMakeLists.txt` to define the build process.
+
+- **`CMakeLists.txt`**: This file contains a set of directives and commands that describe the project's source files and dependencies.
+
+- **Basic `CMakeLists.txt` Example**:
+
+  ```cmake
+  # Specify the minimum version of CMake required.
+  cmake_minimum_required(VERSION 3.10)
+
+  # Set the project name and language.
+  project(MyProject CXX)
+
+  # Specify the C++ standard.
+  set(CMAKE_CXX_STANDARD 17)
+  set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+  # Add an executable target.
+  add_executable(my_app main.cpp)
+  ```
+
+- **Building with CMake**:
+  ```bash
+  mkdir build
+  cd build
+  cmake ..
+  make
+  ```
+
+### Package Management
+
+Managing dependencies in C++ can be complex. Package managers help automate this process.
+
+- **vcpkg (Microsoft)**: A cross-platform package manager.
+- **Conan**: Another popular, cross-platform package manager.
+
+## 2. Key Language Features (Modern C++)
+
+### RAII and Smart Pointers
+
+**RAII (Resource Acquisition Is Initialization)** is a core C++ principle. It means that you tie the life cycle of a resource (like memory, a file handle, or a network socket) to the lifetime of an object. The resource is acquired in the object's constructor and released in its destructor.
+
+**Smart Pointers** are the primary way to implement RAII for memory management. They automatically handle memory deallocation, preventing memory leaks.
+
+- `std::unique_ptr`: A smart pointer that owns and manages another object through a pointer and disposes of that object when the `unique_ptr` goes out of scope. There can only be one `unique_ptr` to an object.
+- `std::shared_ptr`: A smart pointer that retains shared ownership of an object through a pointer. Several `shared_ptr` objects may own the same object. The object is destroyed when the last remaining `shared_ptr` owning it is destroyed.
+- `std::weak_ptr`: A smart pointer that holds a non-owning ("weak") reference to an object that is managed by a `shared_ptr`. It is used to break circular references.
+
+**Always prefer smart pointers over raw pointers (`new` and `delete`) for managing dynamic memory.**
+
+### The Standard Template Library (STL)
+
+The STL is a set of C++ template classes to provide common data structures and functions.
+
+- **Containers**:
+  - `std::vector`: A dynamic array.
+  - `std::string`: A string class.
+  - `std::map`: A key-value map (implemented as a red-black tree).
+  - `std::unordered_map`: A key-value map (implemented as a hash table).
+- **Algorithms**: The `<algorithm>` header provides a rich set of functions for operating on ranges of elements (e.g., `std::sort`, `std::find`, `std::for_each`).
+
+### Lambdas
+
+Lambdas are a concise way to create anonymous functions.
+
+```cpp
+#include <vector>
+#include <algorithm>
+#include <iostream>
+
+int main() {
+    std::vector<int> v = {1, 2, 3, 4, 5};
+    std::for_each(v.begin(), v.end(), [](int n) {
+        std::cout << n << std::endl;
+    });
+    return 0;
+}
+```
+
+## 3. Testing
+
+- **Google Test (`gtest`)**: A popular and powerful C++ testing framework. It provides a rich set of assertions and features for writing tests.
+- **Catch2**: Another popular, modern, and easy-to-use testing framework.
+
+A typical test with Google Test looks like this:
+
+```cpp
+#include "gtest/gtest.h"
+
+int add(int a, int b) {
+    return a + b;
+}
+
+TEST(AddTest, PositiveNumbers) {
+    EXPECT_EQ(add(2, 3), 5);
+}
+```

platforms/docker.md

@@ -0,0 +1,103 @@
+# Working with Docker
+
+This document provides guidelines and best practices for AI agents working with Docker. Docker is a fundamental tool for creating consistent, isolated, and portable development and production environments.
+
+## 1. Core Concepts
+
+A solid understanding of Docker's core concepts is essential.
+
+- **Images**: A read-only template with instructions for creating a Docker container. Images are the blueprints of your application. They are built from a `Dockerfile`.
+- **Containers**: A runnable instance of an image. You can create, start, stop, move, or delete a container. Containers are isolated from one another and from the host machine.
+- **Dockerfile**: A text document that contains all the commands a user could call on the command line to assemble an image. `docker build` uses this file to create an image.
+- **Volumes**: The preferred mechanism for persisting data generated by and used by Docker containers. While bind mounts are dependent on the directory structure of the host machine, volumes are completely managed by Docker.
+- **Docker Hub / Registries**: A registry of Docker images. Docker Hub is the default public registry. You can pull images from a registry and push your own images to it.
+- **Docker Compose**: A tool for defining and running multi-container Docker applications. It uses a YAML file (`docker-compose.yml`) to configure the application's services.
+
+## 2. Dockerfile Best Practices
+
+Writing a clean, efficient, and secure `Dockerfile` is critical.
+
+- **Use a `.dockerignore` file**: Exclude files and directories that are not necessary for the build, such as `.git`, `node_modules`, and temporary files. This reduces the build context size and improves build performance.
+- **Use Multi-Stage Builds**: Use multi-stage builds to separate the build environment from the final runtime environment. This dramatically reduces the size of your final image by excluding build-time dependencies and tools.
+
+  ```dockerfile
+  # Build stage
+  FROM node:18 as builder
+  WORKDIR /app
+  COPY package.json .
+  RUN npm install
+  COPY . .
+  RUN npm run build
+
+  # Final stage
+  FROM nginx:stable-alpine
+  COPY --from=builder /app/build /usr/share/nginx/html
+  EXPOSE 80
+  CMD ["nginx", "-g", "daemon off;"]
+  ```
+
+- **Choose Minimal Base Images**: Start with a minimal base image, like `alpine`, to reduce the image size and attack surface.
+- **Don't Install Unnecessary Packages**: Avoid installing debugging tools or other packages that are not needed in the final image.
+- **Combine `RUN` instructions**: Chain `RUN` commands using `&&` to reduce the number of layers in your image. Clean up temporary files in the same layer.
+
+  ```dockerfile
+  RUN apt-get update && apt-get install -y \
+      package-one \
+      package-two \
+      && rm -rf /var/lib/apt/lists/*
+  ```
+
+- **Leverage Build Cache**: Order your `Dockerfile` instructions from least to most frequently changing. `COPY package.json` and `RUN npm install` should come before `COPY . .` so that you don't have to re-install dependencies every time a source file changes.
+- **Run as a Non-Root User**: Create a non-root user and use the `USER` instruction to run your application. This is a crucial security best practice.
+
+  ```dockerfile
+  RUN addgroup -S appgroup && adduser -S appuser -G appgroup
+  USER appuser
+  ```
+
+## 3. Essential CLI Commands
+
+You will frequently interact with the Docker daemon via the CLI.
+
+### Single Container Management
+
+- `docker build -t <image-name>:<tag> .`: Build an image from a Dockerfile.
+- `docker run [OPTIONS] <image-name>`: Run a container from an image.
+  - `-d`: Detached mode (run in the background).
+  - `-p <host-port>:<container-port>`: Map a port.
+  - `--rm`: Automatically remove the container when it exits.
+  - `-v <volume-name>:<container-path>`: Mount a volume.
+  - `--name <container-name>`: Assign a name to the container.
+- `docker ps`: List running containers. (`-a` to show all).
+- `docker stop <container-id|name>`: Stop a running container.
+- `docker rm <container-id|name>`: Remove a stopped container.
+- `docker logs <container-id|name>`: View the logs of a container.
+- `docker exec -it <container-id|name> <command>`: Execute a command in a running container (e.g., `bash`).
+- `docker images`: List all images on the system.
+- `docker rmi <image-id>`: Remove an image.
+- `docker pull <image-name>:<tag>`: Pull an image from a registry.
+- `docker push <image-name>:<tag>`: Push an image to a registry.
+
+### Multi-Container Management (Docker Compose)
+
+- `docker-compose up`: Build, (re)create, start, and attach to containers for a service. Use `-d` to run in detached mode.
+- `docker-compose down`: Stop and remove containers, networks, images, and volumes. Use `-v` to remove named volumes.
+- `docker-compose ps`: List containers.
+- `docker-compose logs`: View logs from services.
+- `docker-compose build`: Build or rebuild services.
+- `docker-compose exec <service-name> <command>`: Execute a command in a running service.
+
+## 4. Security Best Practices
+
+- **Principle of Least Privilege**:
+  - Always run containers as a non-root user (`USER` instruction).
+  - Use `COPY` instead of `ADD` where possible, as `ADD` can have unexpected behavior (e.g., auto-extracting tarballs).
+- **Reduce Attack Surface**:
+  - Use minimal base images.
+  - Don't install unnecessary packages.
+  - Use multi-stage builds to discard build tools.
+- **Scan for Vulnerabilities**: Use tools like Docker Scout, Trivy, or Snyk to scan your images for known vulnerabilities.
+- **Manage Secrets Securely**:
+  - Do not copy secrets (API keys, passwords) directly into your `Dockerfile`.
+  - Use build-time secrets (`--secret`) or runtime environment variables/Docker secrets to handle sensitive data.
+- **Prevent Privilege Escalation**: Run containers with `--security-opt=no-new-privileges` to prevent processes from gaining new privileges.

platforms/go.md

@@ -0,0 +1,119 @@
+# Working with Go
+
+This document provides guidelines and best practices for AI agents working on Go projects. Go is a statically typed, compiled language known for its simplicity, performance, and excellent support for concurrent programming.
+
+## 1. Development Environment
+
+Go has a strong focus on tooling and a standardized project structure.
+
+### Go Modules
+
+Modern Go projects use Go Modules to manage dependencies. A project is defined as a module, and it's declared with a `go.mod` file in the project's root directory.
+
+- **`go.mod`**: This file defines the module's path (its name), the version of Go it was built with, and its dependencies.
+- **`go.sum`**: This file contains the checksums of the direct and indirect dependencies to ensure reproducible builds. It is automatically generated and updated.
+
+### The `go` command
+
+The `go` command is the main entry point for a suite of tools.
+
+- `go run <file.go>`: Compiles and runs a Go program.
+- `go build`: Compiles the packages and their dependencies.
+- `go test`: Runs tests.
+- `go fmt`: Formats Go source code according to the language's conventions. This should be run frequently.
+- `go get <package>`: Adds a new dependency to the current module.
+- `go mod tidy`: Ensures the `go.mod` file matches the source code's dependencies, adding any missing ones and removing unused ones.
+
+## 2. Basic Syntax
+
+- **Packages**: Every Go program is made up of packages. The `main` package is the entry point for an executable program.
+- **Variables**:
+  - `var name string = "Jules"`: Declares a variable with its type.
+  - `name := "Jules"`: The `:=` syntax is shorthand for declaring and initializing a variable. Go infers the type.
+- **Structs**: A `struct` is a collection of fields. It's used to group data together.
+  ```go
+  type User struct {
+      ID   int
+      Name string
+  }
+  ```
+- **Functions**: Functions can take zero or more arguments and can return multiple values.
+  ```go
+  func add(a int, b int) int {
+      return a + b
+  }
+  ```
+
+## 3. Key Language Features
+
+### Concurrency (Goroutines and Channels)
+
+Go's approach to concurrency is one of its most powerful features.
+
+- **Goroutines**: A goroutine is a lightweight thread managed by the Go runtime. You can start a new goroutine with the `go` keyword.
+  ```go
+  go myFunction() // This will run myFunction concurrently.
+  ```
+- **Channels**: Channels are a typed conduit through which you can send and receive values with the channel operator, `<-`. They are the primary way to communicate between goroutines.
+
+  ```go
+  messages := make(chan string)
+
+  go func() { messages <- "ping" }()
+
+  msg := <-messages
+  fmt.Println(msg) // "ping"
+  ```
+
+### Interfaces
+
+Interfaces in Go provide a way to specify the behavior of an object. An interface is a collection of method signatures. A type implements an interface by implementing its methods. There is no `implements` keyword; the implementation is implicit.
+
+```go
+type Shape interface {
+    Area() float64
+}
+```
+
+### Error Handling
+
+Go has a simple, idiomatic approach to error handling. Functions that can fail return an `error` value as their last return value.
+
+```go
+f, err := os.Open("filename.ext")
+if err != nil {
+    log.Fatal(err)
+}
+// do something with the file f
+```
+
+## 4. Testing
+
+Go has a built-in testing framework provided by the `testing` package.
+
+- Test files are named `*_test.go`.
+- Test functions are named `TestXxx` (where `Xxx` does not start with a lowercase letter) and take `*testing.T` as a parameter.
+- You run tests with the `go test` command.
+
+```go
+// main_test.go
+package main
+
+import "testing"
+
+func TestAdd(t *testing.T) {
+    if add(2, 3) != 5 {
+        t.Errorf("add(2, 3) = %d; want 5", add(2, 3))
+    }
+}
+```
+
+## 5. Standard Library
+
+Go has a rich standard library that provides many useful packages. Key packages include:
+
+- `fmt`: For formatted I/O.
+- `net/http`: For building HTTP clients and servers.
+- `encoding/json`: For encoding and decoding JSON.
+- `os`: For operating system-level operations.
+- `io`: For I/O primitives.