bisos.startAiActivity 0.11

bisos.startAiActivity: Install AI Collaborative Development Templates

Contents

• Overview

• Table of Contents TOC

• Part of BISOS — ByStar Internet Services Operating System

• bisos.startAiActivity is a Command-Only PyCS Facility

• Post-Installation Setup

• Installation

  • Installation With pip

  • Installation With pipx

  • Post-Installation Basic Testing

• Usage

  • Set Templates Base Directory

  • Install Templates Into a Project

  • Install a Subproject Overlay

  • Skills

  • Suspend and Resume AI Collaboration

  • Remove AI Collaboration Files

• Key Files

  • py3/bin/startAiActivity.cs

  • py3/bisos/startAiActivity/updateDblock.py

  • py3/bisos/startAiActivity/dblock_particulars.py

  • PyPi and Github Packaging

• Testing

• Documentation and Blee-Panels

  • bisos.startAiActivity Blee-Panels

• Support

• Planned Improvements

Overview

bisos.startAiActivity installs the ByStar AI collaborative development template set (CLAUDE.md, AI-AGENTS.org, AI-WORKFLOW.org, AI-Activity.org, AI-DevStatus.org, AI-WorkPlan.org) into any project directory or git repo root, wiring it for collaborative development with Claude Code.

bisos.startAiActivity is a python package that uses the PyCS-Framework. It provides the startAiActivity.cs command for installing and managing AI collaborative development templates.

Table of Contents TOC

• Overview

• Part of BISOS — ByStar Internet Services Operating System

• bisos.startAiActivity is a Command-Only PyCS Facility

• Post-Installation Setup

• Installation

  • Installation With pip

  • Installation With pipx

  • Post-Installation Basic Testing

• Usage

  • Set Templates Base Directory

  • Install Templates Into a Project

  • Install a Subproject Overlay

  • Skills

  • Suspend and Resume AI Collaboration

  • Remove AI Collaboration Files

• Key Files

  • `py3/bin/startAiActivity.cs <#py3binstartaiactivitycs>`__

  • `py3/bisos/startAiActivity/updateDblock.py <#py3bisosstartaiactivityupdatedblockpy>`__

  • `py3/bisos/startAiActivity/dblock_particulars.py <#py3bisosstartaiactivitydblock_particularspy>`__

  • PyPi and Github Packaging

• Testing

• Documentation and Blee-Panels

  • bisos.startAiActivity Blee-Panels

• Support

• Planned Improvements

Part of BISOS — ByStar Internet Services Operating System

Layered on top of Debian, BISOS (By* Internet Services Operating System) is a unified and universal framework for developing both internet services and software-service continuums that use internet services. See Bootstrapping ByStar, BISOS and Blee for information about getting started with BISOS.

BISOS is a foundation for The Libre-Halaal ByStar Digital Ecosystem which is described as a cure for losses of autonomy and privacy in a book titled: Nature of Polyexistentials

bisos.startAiActivity is part of BISOS. It is a standalone package that can be used independently of the full BISOS environment.

bisos.startAiActivity is a Command-Only PyCS Facility

bisos.startAiActivity is a command-line tool. It is a PyCS single-unit command service. PyCS is a framework that converges development of CLI tools and services. PyCS is an alternative to FastAPI, Typer and Click.

bisos.startAiActivity uses the PyCS-Framework to:

1. Install AI collaborative development templates (symlinks and safe-copies) into any project directory or git repo root.

2. Expand b:ai:file/particulars org-mode dynamic blocks in installed files using pure Python, without requiring Emacs or bx-dblock.

3. Manage persistent user-config parameters (e.g. templates base path) via ~/.config/bisos/startAiActivity.cs/.

The core of PyCS-Framework is the bisos.b package (the PyCS-Foundation). See bisos.b for an overview.

Post-Installation Setup

After installing, configure the templates base directory. If /bisos/apps/defaults/ai-templates exists on your system it is used as the default automatically. Otherwise, set it explicitly:

startAiActivity.cs -i userConfig_set --parName=templates --parValue=/path/to/ai-templates

Verify the setting:

startAiActivity.cs -i userConfig_get --parName=templates

The AI templates are maintained at: https://github.com/bisos/defaults/tree/master/ai-templates

Installation

The sources for the bisos.startAiActivity pip package are maintained at: https://github.com/bisos-pip/startAiActivity.

The bisos.startAiActivity pip package is available at PYPI as https://pypi.org/project/bisos.startAiActivity

You can install bisos.startAiActivity with pip or pipx.

Installation With pip

If you need access to bisos.startAiActivity as a python module, you can install it with pip:

pip install bisos.startAiActivity

Installation With pipx

If you only need access to bisos.startAiActivity on command-line, you can install it with pipx:

pipx install bisos.startAiActivity

The following commands are made available:

• startAiActivity.cs — installs AI collaborative development templates

Post-Installation Basic Testing

After installation, run:

startAiActivity.cs
startAiActivity.cs -i userConfig_get --parName=templates

Usage

Set Templates Base Directory

startAiActivity.cs -i userConfig_set --parName=templates --parValue=/path/to/ai-templates

Install Templates Into a Project

Install into the current directory:

startAiActivity.cs -i initiate --activity=bisos-pip

Install at the git repo root:

startAiActivity.cs -i initiate --root=repo --activity=bisos-pip

Available activities match subdirectories under the templates base (e.g. bisos-pip, bisos-core, xu-single, blee-panels, lcnt). Run startAiActivity.cs -i examples to see all available activities.

initiate installs the following into the target directory: symlinks for the constant files (CLAUDE.md, AI-AGENTS.org, AI-WORKFLOW.org, AI-Activity.org); safe-copies of the editable files (AI-DevStatus.org, AI-WorkPlan.org, with b:ai:file/particulars dblocks expanded); and symlinks under .claude/ for settings.json, commands/, and skills/ (when the activity ships a _skills/ directory). See the Skills subsection below.

Install a Subproject Overlay

For repos with nested loosely-related subprojects that each want their own work plan and dev status without duplicating the invariant files (AI-AGENTS.org, AI-WORKFLOW.org, .claude/), use initiateSub:

startAiActivity.cs -i initiateSub --activity=bisos-pip

This installs only the subproject-specific state — a slim CLAUDE.md (symlinked to mother/initiateSub/CLAUDE.md), AI-Activity.org symlink, and safe-copies of AI-DevStatus.org and AI-WorkPlan.org. It does NOT install AI-AGENTS.org, AI-WORKFLOW.org, or .claude/ — those are inherited from an ancestor directory via Claude Code’s CLAUDE.md walk-up.

Preconditions (initiateSub refuses if either fails):

1. An ancestor directory must have been initiate-d already (initiateSub walks up looking for a startAiActivity-signature CLAUDE.md symlink).

2. The target directory must not already have a CLAUDE.md.

The --activity flag is required — a subproject may be a different activity from its parent (e.g., a blee-panels subproject inside a bisos-pip repo).

Nested initiateSub is supported: a subproject’s CLAUDE.md satisfies the walk-up precondition for a sub-subproject.

aiSuspend / aiResume / deClaudify all work correctly on subproject overlays. aiResume detects sub vs. base mode from the stashed CLAUDE.md.dormant symlink target.

Skills

When an activity ships a _skills/ directory at its templates root, initiate symlinks it to .claude/skills/ alongside the other .claude/ entries. Claude Code discovers those skills automatically and loads them on demand when the current task calls for them.

Skills are self-contained, filesystem-based packages of task-specific instructions. Each skill is a folder containing a SKILL.md file whose front-matter description tells Claude when to consult the full file. This lets a repo carry deep procedural knowledge (how to write a CS command, how to author a Blee panel, how to release to PyPI) without loading that content on every session — the short descriptions sit in context by default, and Claude reads the full skill only when it matches the task at hand.

The bisos-pip activity currently ships five skills:

• writing-cs-commands — authoring cs.Cmnd subclasses (params, args, classHead dblock, common patterns).

• dblock-authoring — working with poly-dblock begin: blocks, the csuListProc pattern, and dblock-based inline unit tests.

• readme-authorship — writing README.org (repo root — the only authored README; py3/README.rst is generated by pypiProc.sh -i fullPrep and must never be hand-edited).

• blee-panel-authorship — the standard fullUsagePanel-en.org skeleton and dblock content policy.

• bisos-pip-release — end-to-end PyPI release checklist (linters, packaging, Test-PyPI trial, upload).

To author a new skill, add a folder under the appropriate templates directory:

• mother/_skills/<name>/SKILL.md — available to every activity

• <activity>/_skills/<name>/SKILL.md — activity-specific

Each SKILL.md starts with YAML front-matter (----delimited) containing name: and description: fields. The description drives when Claude loads the skill; write it as a concrete trigger (“Use when writing or modifying a PyCS cs.Cmnd subclass”) rather than a topic label.

Suspend and Resume AI Collaboration

When AI collaboration on a project needs to be paused temporarily, use aiSuspend to enter a dormant state and aiResume to restore it.

aiSuspend removes the constant symlinks (CLAUDE.md, AI-AGENTS.org, AI-WORKFLOW.org, AI-Activity.org) and the .claude/ entries, and renames the editable files AI-DevStatus.org and AI-WorkPlan.org to .dormant suffixes so that the collaboration state survives.

startAiActivity.cs -i aiSuspend

aiResume restores the .dormant files, re-installs the symlinks, and re-installs .claude/. The activity is inferred from the AI-Activity.org symlink target or from the Activity: header inside AI-WorkPlan.org.

startAiActivity.cs -i aiResume

Both commands operate on the current directory.

Remove AI Collaboration Files

To permanently remove all AI collaboration files from a project, use deClaudify. Unlike aiSuspend, this is irreversible — it deletes the editable AI-DevStatus.org and AI-WorkPlan.org files along with the symlinks and .claude/ entries.

startAiActivity.cs -i deClaudify

The command is safe: symlinks are only removed if they are actually symlinks, and copied files are only removed if they are regular files. Anything a user has created or converted manually is left intact.

Key Files

An overview of the relevant files of the bisos.startAiActivity package:

py3/bin/startAiActivity.cs

The main CS-MU (Command-Services Multi-Unit). Provides the initiate, aiSuspend, aiResume, deClaudify, userConfig_get, and userConfig_set commands. Uses bisos.b.userConfig_csu for persistent parameter management.

py3/bisos/startAiActivity/updateDblock.py

General dblock dispatch engine. Handlers register under a signature string via registerHandler(sig, fn). expandAll(filePath) does a single-pass regex substitution over the file, dispatching each begin: <signature> block to its registered handler.

py3/bisos/startAiActivity/dblock_particulars.py

Self-registering handler for the b:ai:file/particulars dblock signature. Derives the activity from the AI-Activity.org symlink and builds the companion-docs list by scanning the directory.

PyPi and Github Packaging

All bisos-pip repos in the https://github.com/bisos-pip github organization follow the same structure. They all have setup.py files driven by pypiProc.sh.

Testing

An end-to-end verification harness lives at py3/test/verify.sh. It exercises every command in the startAiActivity.cs surface — user-config read/write, initiate, deClaudify, aiSuspend / aiResume (with base-mode detection), and initiateSub (both the positive case within the repo and a negative case in an isolated /tmp/ dir that expects a EH_Problem_UsageError refusal).

Run it as:

cd py3/test
./verify.sh

The shebang is #!/bin/bash -i — this makes the shell interactive, so ~/.bashrc runs its full body and defines the lpDo alias (from ByStar’s _opDo convention) used throughout the script for uniform logging.

The harness starts from a clean state and leaves a clean state — the test directory contains only verify.sh itself before and after a successful run. Exit code 0 indicates all steps behaved as expected (including the intended refusal in the negative case).

Documentation and Blee-Panels

bisos.startAiActivity is part of ByStar Digital Ecosystem http://www.by-star.net.

This module’s primary documentation is in the form of Blee-Panels. Additional information is also available in: http://www.by-star.net/PLPC/180047

bisos.startAiActivity Blee-Panels

bisos.startAiActivity Blee-Panels are in the ./panels directory. From within Blee and BISOS these panels are accessible under the Blee “Panels” menu.

See file:./panels/bisos.startAiActivity/_nodeBase_/fullUsagePanel-en.org for a starting point.

Support

For support, criticism, comments and questions; please contact the author/maintainer

Mohsen Banan at: http://mohsen.1.banan.byname.net/contact

Planned Improvements

• Upload to PyPI and test as pipx install

• Write fullUsagePanel-en.org Blee-Panel